zero-slop 2.7.6 → 2.7.8

package/README.md

@@ -5,20 +5,28 @@
   <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.7.6-72528F">
+  <img alt="version" src="https://img.shields.io/badge/version-2.7.8-72528F">
 </p>
 
-Take all the slop out of your AI writing. The #1 agentic anti-slop skill.
+Less slop, more pop.
 
-Score your writing 0 to 100 for AI slop, see the exact phrases behind the number, and edit them out without changing a single fact. Free, MIT, scored offline with no account. Worked examples and the full benchmark are at [zero-slop.ai](https://zero-slop.ai).
+Zero Slop finds stock phrasing, mechanical rhythm, vague claims, and canned
+formatting, then gives your AI assistant a guarded editing workflow. Its
+MIT-licensed local checks run offline; your existing AI assistant does the editing.
+See the benchmark at [zero-slop.ai](https://zero-slop.ai).
 
 ![A scored sentence before and after editing](assets/demo.png)
 
 ## Problem
 
-AI writing has a distinct tell: "It's not X. It's Y." "Here's the thing nobody tells you." 
+AI-assisted writing often converges on the same constructions: "It's not X. It's Y."
+"Here's the thing nobody tells you." One phrase proves little. Repetition across
+wording, rhythm, structure, and formatting is the problem.
 
-Zero Slop is an Agent Skill and ships no model. Claude, GPT, or another compatible model does the editing; Zero Slop supplies the workflow and the checks that refuse any change to a name, number, quotation or link. It runs in Claude Code, Cowork, Codex, Cursor, Warp, Zed, and any other harness that reads SKILL.md.
+Zero Slop is an Agent Skill and ships no model. Claude, GPT, or another compatible
+model edits; local tools check names, numbers, quotations, links, code, tables, and
+paths. Your AI compares meaning because matching words cannot catch every changed
+claim. It runs in any harness that reads `SKILL.md`.
 
 ## How to install Zero Slop
 
@@ -42,7 +50,8 @@ npx zero-slop score draft.md   # score without installing anything
 ```
 
 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 it later.
+Claude.ai users can upload the [latest release ZIP](https://github.com/manavmishra/ZeroSlop/releases/latest/download/zero-slop.zip).
+`npx skills update zero-slop --global` updates a skills CLI installation later.
 
 ## How to use Zero Slop
 
@@ -50,8 +59,9 @@ Claude.ai users can upload [`dist/zero-slop.zip`](dist/zero-slop.zip). `npx skil
 /zero-slop (your writing)
 ```
 
-You get the edited draft, a before-and-after score, and the flagged phrases quoted with why. `/zero-slop inspect (your writing)` reviews without rewriting.
-For a folder, `slopscore.py --batch drafts/ --gate 25` fails the build above the threshold.
+You get the edited draft, before-and-after scores, and quoted flagged phrases.
+`/zero-slop inspect (your writing)` reviews without rewriting. For a folder,
+`slopscore.py --batch drafts/ --gate 25` fails above the threshold.
 
 ## The slop that Zero Slop catches
 
@@ -68,9 +78,9 @@ For a folder, `slopscore.py --batch drafts/ --gate 25` fails the build above the
 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.
 
-A reading pass covers defects of the whole document, which no span pattern reaches: one shape repeated seven times, statistics piled into a paragraph,
-paragraphs that shuffle without loss. [`references/eval.md`](references/eval.md) has all
-80 checks.
+A reading pass covers document-wide problems: repeated shapes, crowded statistics,
+and paragraphs that shuffle without loss. [`references/eval.md`](references/eval.md)
+has all 80 checks.
 
 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).
@@ -101,15 +111,13 @@ tools use only Python's standard library.
 
 ## Private learning from your edits
 
-Learning starts only when you hand over both versions: the original output and your edited version. Zero Slop watches nothing on its own: no file monitoring, no browser
-hooks, no reaching into where you publish.
+Learning starts only when you provide the original output and your edited version.
+Zero Slop does not monitor files, browsers, or publishing tools.
 
-Private
-data stays under `$ZERO_SLOP_HOME`.
+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
+This human-in-the-loop learning never retrains the model. A profile selected by name
+can exempt existing watchlist words; it does not learn cadence, tone, or a complete
 style.
 
 ## What's inside
@@ -120,16 +128,18 @@ with [`scripts/register.py`](scripts/register.py) running the reading pass.
 [`bench/README.md`](bench/README.md) documents every benchmark with its limits.
 [zero-slop.ai](https://zero-slop.ai) has the same reference as browsable pages, plus the [benchmark in full](https://zero-slop.ai/benchmark/).
 
-## Evidence
+## Testing and limits
 
 ### Against other tools, same model, same drafts
 
-We reran Zero Slop, [avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing),
+The saved replay ran 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   samples, each with
-GPT-5.4, high reasoning, batches of three, and its pinned instructions.
+[humanizer](https://github.com/blader/humanizer) on the same 18 drafts, each with
+GPT-5.4, high reasoning, batches of three, and pinned instructions. The Zero Slop
+outputs came from v2.5.9; later releases rescore those frozen outputs but do not
+pretend to have regenerated them.
 
-| Method | Mean writing score ↓ | Passed all Zero Slop checks | Important details kept | Average length change |
+| Method | Mean writing score ↓ | Passed Zero Slop's local gates | Source check passed | Average length change |
 |---|---:|---:|---:|---:|
 | Original drafts | 76.3 | 0/18 | — | — |
 | Zero Slop | 12.8 | 18/18 | 18/18 | -8.9% |
@@ -151,19 +161,23 @@ rates, and a method-hidden quality ranking.
 ![Method-hidden quality ranking, lower is better](assets/bench-blind-quality.png)
 
 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.7.6 matched the prior 84.2% result
-with every frozen document score unchanged, all 18 human controls clear and all 18 search
-cases still caught: the release moves what the gate asks and leaves the meter
-untouched. Median throughput was 2.32% lower across 12 runs, which is local timing
-noise and no kind of speed claim.
+universal ranking. Drafts, mappings, verdicts, hashes, version records, and limits are
+in [`bench/README.md`](bench/README.md). The separate method-hidden two-way replay used
+Zero Slop v2.6.0 and is preserved in
+[`bench/incumbent-blind-replay/`](bench/incumbent-blind-replay/).
+
+For the 38-item editorial panel, the current scorer matched the prior 84.2% result.
+All frozen scores stayed unchanged, all 18 human controls remained below the gate,
+and all 18 obvious search cases remained above it. These fixed-sample checks are not
+proof of general accuracy. We recorded 6.51% higher median throughput across 12 interleaved
+local runs; treat that as machine noise, not a speed claim.
 
 ### Speed
 
-On one Apple silicon Mac: 1,000 documents in 2.1956 seconds (455.5 per second), a
-15,201-word document in 0.3225 seconds, the slowest stress case in 2.2577 seconds, an
-8,000-word learning pass in 0.1811 seconds. Editing time is excluded; expect different numbers on different machines.
+On one busy Apple silicon Mac: 1,000 documents in 3.2233 seconds (310.2 per second),
+a 15,201-word document in 0.4757 seconds, the slowest stress case in 3.3487 seconds,
+and an 8,000-word learning pass in 0.2284 seconds. Editing time is excluded; expect
+different results on other machines and loads.
 
 ### Current models
 
@@ -183,9 +197,9 @@ Beemo, raw responses averaged
 
 ## Where Zero Slop came from
 
-Zero Slop enhances work done by  no-ai-slop, humanizer, de-slop, stop-slop, unslop-text and
-avoid-ai-writing, by adding a slop score, source protection, separate editorial passes,
-private learning, portfolio analysis and release tests.
+Zero Slop builds on work by no-ai-slop, humanizer, de-slop, stop-slop, unslop-text,
+and avoid-ai-writing. It adds 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)
 

package/SKILL.md

@@ -2,7 +2,7 @@
 name: zero-slop
 license: MIT
 metadata:
-  version: "2.7.6"
+  version: "2.7.8"
   author: manavmishra
 description: Turn drafts into sharp, natural prose or inspect them without rewriting. Zero Slop runs inside the user's existing AI assistant; Claude, GPT, or another compatible model reads and edits in context while local tools point to exact phrases and protect the source. Use when the user asks to humanize or de-slop writing, inspect AI-sounding patterns, fix text that reads like ChatGPT, polish outward-facing prose, draft social or LinkedIn content, or apply a final quality check to prose the agent generated. The workflow preserves facts, voice, and format and learns privately from repeated, reason-labelled human edits.
 ---
@@ -504,6 +504,17 @@ Re-run the local tools. A version clears the fact gate only when ALL hold:
   wording may change; their content and nesting may not. This deterministic
   check still cannot see a subtly reframed claim, changed emphasis, or shifted
   implication, so the judgment pass below remains mandatory
+- if a reviewer confirms that a dropped figure was an unsourced flourish rather
+  than a fact, record the decision in a source-bound JSON file and rerun:
+
+  ```
+  python3 <skill-root>/scripts/slopscore.py --fidelity \
+    --adjudication <ruling.json> <original> <rewrite>
+  ```
+
+  The file contains schema `1`, the SHA-256 of the exact original text, and
+  `allow_dropped_figures`. It can excuse only figures found in that source; it
+  cannot weaken checks for names, quotations, links, feelings, or structure
 - shape (social genres only): the scorer reports `broetry` when most
   paragraphs are single sentences and fragments run three or more deep. This
   is its own axis, never folded into the score, because broetry is a slop tell
@@ -741,9 +752,10 @@ facts, meaning, structure, and whether the writing is performing rather than say
 ```
 
 The "two-part contrasts / announcements" row is the performed-register count from
-step 2. Add a line for the register gate beside it: `Register gate: 58 checks, 0
-failed` or the count that did fail. A report without it is a report that skipped the
-checklist. **Print it even when both numbers are zero**, and print it on a draft that
+step 2. Add a line beside it: `Final review: 80 checks, 0 failed` or the count
+that did fail. The 80 checks include AI reading, local measurements, and source
+protection; do not imply that one script performed all of them. **Print it even when
+both numbers are zero**, and print it on a draft that
 scored clean. It is the only evidence that the pass ran; a report without it is a
 report that skipped it.
 

package/bin/zero-slop.mjs

@@ -5,10 +5,10 @@
 // mirrors rather than people. This is the executable half: it installs the same
 // runtime the tarball already carries, and runs the scorer without a checkout.
 
-import { cp, mkdir, readFile, rm, stat } from "node:fs/promises";
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, parse, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -41,7 +41,7 @@ Usage
 Install targets
   --harness   ${Object.keys(HARNESS_DIRS).join(", ")}   (default: claude)
   --dir       install into an explicit directory instead
-  --force     overwrite an existing installation
+  --force     replace a verified Zero Slop installation
 
 Examples
   npx zero-slop install                    # ~/.claude/skills/zero-slop
@@ -63,10 +63,18 @@ function parseArgs(argv) {
       break;
     }
     if (a === "--force") flags.force = true;
-    else if (a === "--harness" || a === "--dir") flags[a.slice(2)] = argv[++i];
-    else if (a.startsWith("--harness=")) flags.harness = a.split("=")[1];
-    else if (a.startsWith("--dir=")) flags.dir = a.split("=")[1];
-    else rest.push(a);
+    else if (a === "--harness" || a === "--dir") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("--")) throw new Error(`${a} needs a value`);
+      flags[a.slice(2)] = value;
+      i += 1;
+    } else if (a.startsWith("--harness=")) {
+      flags.harness = a.slice("--harness=".length);
+      if (!flags.harness) throw new Error("--harness needs a value");
+    } else if (a.startsWith("--dir=")) {
+      flags.dir = a.slice("--dir=".length);
+      if (!flags.dir) throw new Error("--dir needs a value");
+    } else rest.push(a);
   }
   return { flags, rest, passthrough };
 }
@@ -92,21 +100,77 @@ async function exists(p) {
   }
 }
 
+function assertNarrowTarget(dest) {
+  const target = resolve(dest);
+  const forbidden = new Set([
+    parse(target).root,
+    resolve(homedir()),
+    resolve(process.cwd()),
+    ROOT,
+  ]);
+  if (forbidden.has(target)) {
+    throw new Error(`refusing broad install target: ${target}`);
+  }
+}
+
+async function verifiedExistingInstall(dest) {
+  const info = await lstat(dest);
+  if (info.isSymbolicLink() || !info.isDirectory()) return false;
+  const entries = await readdir(dest);
+  if (!entries.length) return true;
+  try {
+    const skill = await readFile(join(dest, "SKILL.md"), "utf8");
+    const header = skill.split("---", 3)[1] ?? "";
+    const runtime = await lstat(join(dest, "scripts", "slopscore.py"));
+    const patterns = await lstat(join(dest, "data", "patterns.json"));
+    return /^name:\s*zero-slop\s*$/m.test(header)
+      && runtime.isFile() && patterns.isFile();
+  } catch {
+    return false;
+  }
+}
+
 async function install(flags) {
   const dest = targetDir(flags);
-  if ((await exists(dest)) && !flags.force) {
+  assertNarrowTarget(dest);
+  const present = await exists(dest);
+  if (present && !flags.force) {
     console.error(
       `zero-slop is already installed at ${dest}\n` +
         `Re-run with --force to overwrite it, or --dir to install elsewhere.`,
     );
     return 1;
   }
-  // Replace rather than merge: a stale reference file left behind by an older
-  // version is a silent behaviour change, which is the failure this avoids.
-  await rm(dest, { recursive: true, force: true });
-  await mkdir(dest, { recursive: true });
-  for (const entry of PAYLOAD) {
-    await cp(join(ROOT, entry), join(dest, entry), { recursive: true });
+  if (present && !(await verifiedExistingInstall(dest))) {
+    throw new Error(
+      `refusing to overwrite ${dest}: it is not a Zero Slop installation`,
+    );
+  }
+
+  // Build the complete payload beside the destination before replacing an
+  // existing install. A copy failure therefore leaves the working version
+  // untouched, and the backup is restored if the final rename fails.
+  const nonce = `${process.pid}-${Date.now()}`;
+  const staged = `${dest}.installing-${nonce}`;
+  const backup = `${dest}.backup-${nonce}`;
+  await mkdir(dirname(dest), { recursive: true });
+  await mkdir(staged);
+  try {
+    for (const entry of PAYLOAD) {
+      await cp(join(ROOT, entry), join(staged, entry), { recursive: true });
+    }
+    if (present) await rename(dest, backup);
+    try {
+      await rename(staged, dest);
+    } catch (exc) {
+      if (present && (await exists(backup)) && !(await exists(dest))) {
+        await rename(backup, dest);
+      }
+      throw exc;
+    }
+    if (present) await rm(backup, { recursive: true, force: true });
+  } finally {
+    await rm(staged, { recursive: true, force: true });
   }
   console.log(`Installed zero-slop ${await version()} into ${dest}`);
   console.log("Restart your agent, then run: /zero-slop (your writing)");
@@ -147,7 +211,13 @@ async function main() {
     console.log(usage(v));
     return command || argv.length ? 0 : 0;
   }
-  if (command === "install") return install(flags);
+  if (command === "install") {
+    if (rest.length !== 1 || passthrough.length) {
+      console.error("install accepts only --harness, --dir, and --force");
+      return 2;
+    }
+    return install(flags);
+  }
   if (command === "where") {
     console.log(targetDir(flags));
     return 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zero-slop",
-  "version": "2.7.6",
-  "description": "An Agent Skill that scores AI-sounding prose 0-100 locally and rewrites it without losing a fact. Runs inside Claude Code, Codex, Cursor, Warp, Zed and other SKILL.md agents. Offline, zero dependencies, MIT.",
+  "version": "2.7.8",
+  "description": "An Agent Skill that scores AI-sounding prose locally, guides the host AI through an editorial rewrite, and checks changed source details. The local tools run offline with zero dependencies.",
   "bin": {
     "zero-slop": "bin/zero-slop.mjs"
   },

package/references/eval.md

@@ -232,8 +232,11 @@ the report even when they are zero.
     (`figure_evidence`) and waits. Rule on each one: a figure with a source, a unit,
     a baseline or a citation must be restored; an unsourced multiplier or statistic
     doing an intensifier's job -- "the 10x move", "tenfold", "~70% of pilots fail" --
-    was right to cut, and you record that ruling rather than letting the gate assume
-    it. Never invent a citation to keep a number alive. Unruled means unresolved:
+    was right to cut. Record that ruling in a source-bound JSON file and rerun
+    `slopscore.py --fidelity --adjudication ruling.json original rewrite`; the
+    file carries schema `1`, the exact original text's SHA-256, and an
+    `allow_dropped_figures` list. Never invent a citation to keep a number alive.
+    Unruled means unresolved:
     the default is that the figure stays, so silence here is a failed check and not
     a pass. Both errors are real. Restoring a flourish is how a rewrite ships fake
     precision, and dropping a measurement is how it ships a lie.

package/scripts/learn.py

@@ -71,8 +71,8 @@ SHARED_LOG = DATA / "learned-log.md"
 # default and lives outside the repository — a checkout should never carry one
 # person's writing. Override with ZERO_SLOP_HOME to relocate or to share a
 # deliberate team-scoped store.
-HOME = Path(os.environ.get("ZERO_SLOP_HOME",
-                           Path.home() / ".zero-slop")).expanduser()
+HOME = Path(os.environ.get("ZERO_SLOP_HOME")
+            or Path.home() / ".zero-slop").expanduser()
 OBS = HOME / "reflections.json"
 LOCAL = HOME / "learned.json"
 LOCAL_LOG = HOME / "learned-log.md"

package/scripts/register.py

@@ -51,6 +51,15 @@ BUDGETS = {
     "referent_cluster": (1.5, 1),
     "adjective_inflation": (1.5, 1),
 }
+# A short draft cannot support a per-1,000-word rate, so it uses an absolute
+# recurrence floor instead. Two families appear once in the certified-human
+# corpus; requiring two keeps those controls quiet while still closing the old
+# "everything under 300 words passes" bypass.
+SHORT_FLOORS = {
+    **{key: floor for key, (_budget, floor) in BUDGETS.items()},
+    "dangling_pointer": 2,
+    "referent_cluster": 2,
+}
 
 # "X, not Y." and "A rather than B." The corrective appositive. Each instance is
 # usually careful writing, which is why no pattern list contains it.
@@ -287,7 +296,7 @@ def measure(text: str) -> dict:
 
     paras = paragraphs(prose)
     lengths = [len(p.split()) for p in paras]
-    uniformity = (
+    paragraph_uniformity = (
         round(statistics.pstdev(lengths) / statistics.mean(lengths), 2)
         if len(lengths) > 2 and statistics.mean(lengths)
         else None
@@ -300,7 +309,7 @@ def measure(text: str) -> dict:
     fragments = verbless_fragments(prose)
     thin = thin_sections(text)
     clusters = referent_clusters(text)
-    uniformity, column = table_row_uniformity(text)
+    table_uniformity, column = table_row_uniformity(text)
 
     return {
         "words": words,
@@ -311,14 +320,14 @@ def measure(text: str) -> dict:
         "verbless_fragment": {"count": len(fragments), "per_1k": per_k(len(fragments)), "hits": fragments[:5]},
         "thin_section": {"count": len(thin), "per_1k": per_k(len(thin)), "hits": thin[:6]},
         "referent_cluster": {"count": len(clusters), "per_1k": per_k(len(clusters)), "hits": clusters[:3]},
-        "table_uniformity": {"share": uniformity, "column": column},
+        "table_uniformity": {"share": table_uniformity, "column": column},
         "subtractive_contrast": {"count": len(subtractive), "per_1k": per_k(len(subtractive)), "hits": subtractive[:12]},
         "comma_series": {"count": len(series), "per_1k": per_k(len(series))},
         "significance_scaffolding": {"count": len(significance), "per_1k": per_k(len(significance)), "hits": significance[:6]},
         "classifier_scaffolding": {"count": len(classifier), "per_1k": per_k(len(classifier)), "hits": classifier[:6]},
         "inanimate_agent": {"count": len(inanimate), "per_1k": per_k(len(inanimate)), "hits": inanimate[:8]},
         "repeated_openings": {"count": len(repeated), "per_1k": per_k(len(repeated)), "hits": repeated[:6]},
-        "paragraph_uniformity": uniformity,
+        "paragraph_uniformity": paragraph_uniformity,
     }
 
 
@@ -329,7 +338,10 @@ def verdicts(m: dict) -> list[tuple[str, float, float, bool]]:
     for key, (budget, floor) in BUDGETS.items():
         value = m[key]["per_1k"]
         count = m[key]["count"]
-        ok = short or value <= budget or count < floor
+        # Rates are unstable on short drafts, but an absolute budget is not.
+        # Below MIN_WORDS, use only the recurrence floor; otherwise require
+        # both enough instances and a rate over budget before failing.
+        ok = count < SHORT_FLOORS[key] if short else value <= budget or count < floor
         rows.append((key, value, budget, ok))
     return rows
 
@@ -360,8 +372,11 @@ def render(m: dict, name: str) -> str:
         out.append(f"  Under {MIN_WORDS} words. Rates are not reported: one instance in a short")
         out.append("  document swamps the rate. Counts only.")
         out.append("")
+        states = {key: ok for key, _value, _budget, ok in verdicts(m)}
         for key in BUDGETS:
-            out.append(f"        {LABEL[key]:<32} {m[key]['count']:>6} found")
+            mark = "ok  " if states[key] else "OVER"
+            out.append(f"  {mark}  {LABEL[key]:<32} {m[key]['count']:>6} found"
+                       f"   limit {SHORT_FLOORS[key] - 1}")
         return "\n".join(out)
     for key, value, budget, ok in verdicts(m):
         mark = "ok  " if ok else "OVER"
@@ -500,8 +515,8 @@ def read_packet(text: str, name: str) -> dict:
         "file": name,
         "instruction": (
             "Work section by section, one pass per section: answer all of section A "
-            "before opening B, and so on. Sixty questions held at once get a "
-            "sixty-th of your attention each; ten at a time get read. Answer with "
+            "before opening B, and so on. Do not hold the whole checklist in "
+            "attention at once; work in small sections and answer each item. Answer with "
             "pass or fail; where a question asks for a count, give the number. Quote "
             "exact spans as evidence; never paraphrase. Then fill _coverage: map "
             "every paragraph id to \"clean\" or to the list of check ids that fire "
@@ -547,9 +562,22 @@ def check_evidence(raw: str, answers: dict, checks: list[dict]) -> list[str]:
         if not isinstance(got, dict):
             continue
         answer = got.get("answer")
-        quotes = [q for q in (got.get("evidence") or []) if isinstance(q, str)]
+        raw_quotes = got.get("evidence")
+        if raw_quotes is not None and not isinstance(raw_quotes, list):
+            problems.append(f"{check['id']} evidence must be a list of exact quotes")
+            raw_quotes = []
+        elif isinstance(raw_quotes, list) and any(not isinstance(q, str) for q in raw_quotes):
+            problems.append(f"{check['id']} evidence entries must all be strings")
+        quotes = [q for q in (raw_quotes or []) if isinstance(q, str)]
         count = got.get("count")
 
+        if ("___" in check["title"] and "count" in check["title"].lower()
+                and (isinstance(count, bool) or not isinstance(count, int) or count < 0)):
+            problems.append(f"{check['id']} is missing a required count")
+        elif count is not None and (isinstance(count, bool)
+                                    or not isinstance(count, int) or count < 0):
+            problems.append(f"{check['id']} count must be a non-negative integer or null")
+
         if answer == "fail" and not quotes:
             problems.append(f"{check['id']} failed with no quoted evidence")
         if answer == "fail" and isinstance(count, int) and count == 0:
@@ -572,6 +600,9 @@ def check_evidence(raw: str, answers: dict, checks: list[dict]) -> list[str]:
 
 def verdict(text: str, answers: dict) -> tuple[int, str]:
     """Combine the measured rates with the model's read. Both must clear."""
+    if not isinstance(answers, dict):
+        return 1, ("Register verdict\n\n  FAIL    answer packet must be a JSON object "
+                   "keyed by checklist id. No checks were accepted.")
     m = measure(text)
     checks = [c for c in load_checks() if not c["skip"] and not c["auto"]]
     out = ["Register verdict", ""]
@@ -602,7 +633,10 @@ def verdict(text: str, answers: dict) -> tuple[int, str]:
         out.append(f"    {state:<5} {qid:<5}{check['title'][:48]}{shown}")
         if got["answer"] == "fail":
             failed.append(qid)
-            for quote in (got.get("evidence") or [])[:3]:
+            quotes = got.get("evidence")
+            if not isinstance(quotes, list):
+                quotes = []
+            for quote in quotes[:3]:
                 out.append(f"           · {str(quote)[:84]}")
     out.append("")
 
@@ -614,12 +648,53 @@ def verdict(text: str, answers: dict) -> tuple[int, str]:
         out.append("            paragraph nobody read; the checklist was answered from memory.")
         failed.append("coverage (missing)")
     else:
+        known_paragraphs = set(para_ids)
+        # JSON object keys arrive as strings, but verdict() is also a public
+        # library function. Treat an in-process packet with non-string keys as
+        # invalid input instead of letting sorting or joining raise TypeError.
+        unknown = sorted(
+            (key for key in coverage if not isinstance(key, str)
+             or key not in known_paragraphs),
+            key=str,
+        )
         unread = [i for i in para_ids if i not in coverage]
+        coverage_problems = []
+        valid_check_ids = {c["id"] for c in checks}
+        if unknown:
+            coverage_problems.append(
+                "unknown paragraph id(s): " + ", ".join(map(str, unknown[:8])))
+        for para_id in para_ids:
+            if para_id not in coverage:
+                continue
+            value = coverage[para_id]
+            if value == "clean":
+                continue
+            if not isinstance(value, list) or not value:
+                coverage_problems.append(
+                    f"{para_id} must be clean or a non-empty list of failed check ids")
+                continue
+            if any(not isinstance(check_id, str) for check_id in value):
+                coverage_problems.append(f"{para_id} check ids must be strings")
+                continue
+            if len(value) != len(set(value)):
+                coverage_problems.append(f"{para_id} repeats a check id")
+            for check_id in value:
+                if check_id not in valid_check_ids:
+                    coverage_problems.append(f"{para_id} names unknown check {check_id}")
+                else:
+                    referenced = answers.get(check_id)
+                    if not isinstance(referenced, dict) or referenced.get("answer") != "fail":
+                        coverage_problems.append(
+                            f"{para_id} names {check_id}, but that check did not fail")
         if unread:
             out.append(f"    FAIL    {len(unread)} paragraph(s) never dispositioned: "
                        + ", ".join(unread[:8]))
             failed.append("coverage (incomplete)")
-        else:
+        if coverage_problems:
+            for problem in coverage_problems:
+                out.append(f"    FAIL    {problem}")
+            failed.append("coverage (invalid)")
+        if not unread and not coverage_problems:
             flagged = sum(1 for v in coverage.values() if v != "clean")
             out.append(f"    ok      all {len(para_ids)} paragraphs dispositioned, "
                        f"{flagged} carrying findings")
@@ -634,7 +709,12 @@ def verdict(text: str, answers: dict) -> tuple[int, str]:
         out.append("    Re-read the draft and quote the exact span, or change the answer.")
     else:
         answered = sum(1 for c in checks if isinstance(answers.get(c["id"]), dict))
-        quoted = sum(len(answers.get(c["id"], {}).get("evidence") or []) for c in checks)
+        quoted = 0
+        for check in checks:
+            got = answers.get(check["id"])
+            quotes = got.get("evidence") if isinstance(got, dict) else None
+            if isinstance(quotes, list):
+                quoted += sum(isinstance(quote, str) for quote in quotes)
         if not answered:
             out.append("    none    no answer matched any check id. The answers file is for a")
             out.append("            different checklist, or the ids are wrong.")

package/scripts/rerank.py

@@ -36,7 +36,7 @@ def _tier(s):
     return 0 if s["preserved"] else 1
 
 
-def rank(original, candidates, genre=None):
+def rank(original, candidates, genre=None, adjudicated=None):
     """candidates: {name: text}. Returns them scored and sorted, best first.
 
     Sort key: fidelity tier first (a fabrication can never win), then soft quality,
@@ -55,7 +55,7 @@ def rank(original, candidates, genre=None):
     data = slopscore.load_patterns()
     scored = []
     for name, text in candidates.items():
-        s = slopscore.rewrite_score(original, text, genre, data)
+        s = slopscore.rewrite_score(original, text, genre, data, adjudicated)
         s["name"], s["text"] = name, text
         scored.append(s)
     scored.sort(key=lambda s: (_tier(s), -s["soft"], s["after_ai"],
@@ -93,6 +93,8 @@ def main(argv=None):
     ap.add_argument("--original", required=True, metavar="FILE")
     ap.add_argument("--candidates", metavar="JSON_FILE")
     ap.add_argument("--genre")
+    ap.add_argument("--adjudication", metavar="JSON_FILE",
+                    help="source-bound rulings for figures intentionally removed")
     ap.add_argument("--out", metavar="FILE")
     ap.add_argument("--emit", action="store_true")
     ap.add_argument("files", nargs="*")
@@ -122,8 +124,15 @@ def main(argv=None):
     if len(candidates) < 2:
         ap.error("give at least two candidate rewrites to choose between")
 
+    adjudicated = None
+    if args.adjudication:
+        import slopscore
+        try:
+            adjudicated = slopscore.load_adjudication(args.adjudication, original)
+        except ValueError as exc:
+            ap.error(str(exc))
     try:
-        scored = rank(original, candidates, args.genre)
+        scored = rank(original, candidates, args.genre, adjudicated)
     except ValueError as exc:
         ap.error(str(exc))
     print(render(scored))

package/scripts/safeio.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
 """Small, stdlib-only primitives for durable and concurrency-safe state updates.
 
-Zero Slop's scorer is read-only, but the learning and calibration tools perform
-read-modify-write updates. Atomic replacement prevents torn JSON; lock directories
-prevent two processes from silently overwriting each other's observations.
+Zero Slop never alters a scored draft. Learning and calibration update private state,
+and an interactive score can update one local, one-time note marker. Atomic
+replacement prevents torn files; lock directories prevent concurrent processes from
+silently overwriting each other's state.
 """
 from contextlib import contextmanager
 import hashlib

package/scripts/slopscore.py

@@ -24,6 +24,8 @@ The phrase lists live beside this script in ../data/patterns.json and
 """
 import bisect
 import functools
+import hashlib
+import importlib.util
 import json
 import math
 import re
@@ -37,7 +39,19 @@ SHAPE_SOLO_THRESHOLD = 0.62  # calibrated, see calibrate.py --shape
 # Where personal voice profiles live — outside the repo, since they are the
 # user's own writing. One file per author, git-ignored by construction.
 import os
-HOME = Path(os.environ.get("ZERO_SLOP_HOME", Path.home() / ".zero-slop")).expanduser()
+
+# The scorer is both a CLI and an importable single-file module. Load its
+# adjacent helper by path so importlib callers do not have to modify sys.path,
+# and so an unrelated third-party module named ``safeio`` cannot be selected.
+_SAFEIO_SPEC = importlib.util.spec_from_file_location(
+    "_zero_slop_safeio", Path(__file__).resolve().with_name("safeio.py"))
+if _SAFEIO_SPEC is None or _SAFEIO_SPEC.loader is None:  # pragma: no cover
+    raise ImportError("cannot load Zero Slop's adjacent safeio.py")
+_SAFEIO = importlib.util.module_from_spec(_SAFEIO_SPEC)
+_SAFEIO_SPEC.loader.exec_module(_SAFEIO)
+atomic_write_text = _SAFEIO.atomic_write_text
+file_locks = _SAFEIO.file_locks
+HOME = Path(os.environ.get("ZERO_SLOP_HOME") or Path.home() / ".zero-slop").expanduser()
 VOICE_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}\Z")
 
 
@@ -45,6 +59,94 @@ class PatternData(dict):
     """JSON-compatible pattern mapping with an out-of-band compiled plan."""
 
 
+# One-time note asking for a GitHub star.
+#
+# 448 machines cloned this in a fortnight and seventeen people had starred it,
+# because nothing ever asked. The risk in fixing that is obvious: a tool whose
+# whole job is deleting manipulative filler cannot itself nag, so every rule
+# below is a restriction rather than a reach.
+#
+#   - Once per machine, ever. A marker in the state directory, not a counter
+#     that resets.
+#   - Not until the third run, so it asks people who kept using it rather than
+#     people evaluating it once.
+#   - Never when the output is being read by a machine: --json, --batch,
+#     --gate, or any run whose stdout is not a terminal. CI logs stay clean.
+#   - No prompt, no keypress, no opening a browser, no network call. One line
+#     to stderr, so it cannot corrupt piped output even if the checks above
+#     were somehow wrong.
+#   - ZERO_SLOP_NO_NOTES=1 turns it off for good.
+NOTES_FILE = HOME / "notes.json"
+STAR_NOTE_AFTER_RUNS = 3
+
+
+def _load_notes():
+    try:
+        with open(NOTES_FILE, encoding="utf-8") as fh:
+            data = json.load(fh)
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _save_notes(state):
+    try:
+        atomic_write_text(NOTES_FILE, json.dumps(state) + "\n", mode=0o600)
+        return True
+    except OSError:
+        return False  # a read-only home must never break a score
+
+
+def star_note_is_due(argv=None, isatty=None, env=None):
+    """Decide without writing anything, so the rule is testable in isolation."""
+    argv = sys.argv[1:] if argv is None else argv
+    env = os.environ if env is None else env
+    if env.get("ZERO_SLOP_NO_NOTES"):
+        return False
+    if any(flag in argv for flag in ("--json", "--batch", "--gate")):
+        return False
+    if not (sys.stdout.isatty() if isatty is None else isatty):
+        return False
+    state = _load_notes()
+    if state.get("star_note_shown"):
+        return False
+    return int(state.get("human_runs", 0)) + 1 >= STAR_NOTE_AFTER_RUNS
+
+
+def record_human_run(argv=None, isatty=None, env=None):
+    """Count this run and, if it is the one, return the note to print."""
+    argv = sys.argv[1:] if argv is None else argv
+    env = os.environ if env is None else env
+    if env.get("ZERO_SLOP_NO_NOTES"):
+        return None
+    if any(flag in argv for flag in ("--json", "--batch", "--gate")):
+        return None
+    if not (sys.stdout.isatty() if isatty is None else isatty):
+        return None
+    try:
+        # A short best-effort lock prevents simultaneous terminal runs from
+        # both printing the one-time note. Contention or a read-only state
+        # directory must never delay or fail the score itself.
+        with file_locks([NOTES_FILE], timeout=0.25):
+            state = _load_notes()
+            if state.get("star_note_shown"):
+                return None
+            state["human_runs"] = int(state.get("human_runs", 0)) + 1
+            due = state["human_runs"] >= STAR_NOTE_AFTER_RUNS
+            if due:
+                state["star_note_shown"] = True
+            if not _save_notes(state):
+                return None
+    except (OSError, SystemExit):
+        return None
+    if not due:
+        return None
+    return ("\n  If Zero Slop has been useful, a star helps people find it: "
+            "https://github.com/manavmishra/ZeroSlop\n"
+            "  This is the only time you will see this. "
+            "ZERO_SLOP_NO_NOTES=1 silences all notes.")
+
+
 def _voice_path(name):
     """Resolve a profile name without letting it become a filesystem path."""
     if not VOICE_NAME.fullmatch(name or "") or name in (".", ".."):
@@ -159,6 +261,39 @@ def _apply_voice(base, name):
 SENT_SPLIT = re.compile(r"(?<=[.!?])[\")”’]?\s+(?=[A-Z“\"(0-9])")
 WORD = re.compile(r"[A-Za-z’']+")
 
+
+# A quoted span longer than this is a passage, not a named tell, and stays in
+# scope. Short enough to exempt "delve" or "it's not just X, it's Y"; short
+# enough that quoting cannot be used to smuggle paragraphs past the meter.
+QUOTE_SKIP_LIMIT = 200
+
+_BLOCKQUOTE_SCAN_RX = re.compile(r"(?m)^[ \t]*>[ \t]?.*$")
+_INLINE_QUOTE_RXS = (
+    re.compile(rf'"[^"\n]{{0,{QUOTE_SKIP_LIMIT}}}"'),
+    re.compile(rf"“[^”\n]{{0,{QUOTE_SKIP_LIMIT}}}”"),
+)
+
+
+def mask_quoted(text):
+    """Blank quoted material for the pattern meter, keeping every offset.
+
+    Naming a cliche in order to discuss it is the opposite of committing it,
+    and step 0 of SKILL.md has always said to skip quotes. Only the phrase
+    meter and the lexicon honour that: rhythm, readability, word variety and
+    formatting still read the quotation, because a quote a writer chose to
+    include is part of how the finished page reads.
+
+    Spans are replaced character for character, so sentence offsets, word
+    counts and hit positions are identical to the unmasked text.
+    """
+    def blank(match):
+        return re.sub(r"[^\n]", " ", match.group(0))
+
+    text = _BLOCKQUOTE_SCAN_RX.sub(blank, text)
+    for rx in _INLINE_QUOTE_RXS:
+        text = rx.sub(blank, text)
+    return text
+
 # Normalise only detector-evasion characters, never ordinary non-Latin prose.
 # A Cyrillic or Greek lookalike is mapped only when it appears in the same word
 # as an ASCII letter (for example, dеlvе). This keeps Russian and Greek text
@@ -418,6 +553,10 @@ def score_text(text, data, formal=False):
                         if n_words >= 200 else None)
     sent_spans = _sentence_spans(text)
     sents = [text[a:b].replace("\n", " ") for a, b in sent_spans]
+    # Same string with quotations blanked out, used only by the phrase meter
+    # and the lexicon. Offsets match `text` exactly.
+    scan_text = mask_quoted(text)
+    scan_sents = [scan_text[a:b].replace("\n", " ") for a, b in sent_spans]
     hits = []
     pattern_spans = []  # (start, end, lower-rx, compiled-rx) for dedup below
 
@@ -449,10 +588,10 @@ def score_text(text, data, formal=False):
             continue
         if hints:
             if lowercase_text is None:
-                lowercase_text = text.lower()
+                lowercase_text = scan_text.lower()
             if not any(hint in lowercase_text for hint in hints):
                 continue
-        for m in compiled.finditer(text):
+        for m in compiled.finditer(scan_text):
             hits.append({
                 "cat": category, "name": name, "w": weight,
                 "quote": m.group(0)[:90].strip(),
@@ -484,7 +623,7 @@ def score_text(text, data, formal=False):
                    and (term in rx_lower or compiled.search(matched))
                    for ps, pe, rx_lower, compiled in pattern_spans)
 
-    candidates = [candidate for candidate in _term_candidates(text, data["lexicon"])
+    candidates = [candidate for candidate in _term_candidates(scan_text, data["lexicon"])
                   if not _pattern_owns(candidate[:2], candidate[2], candidate[4])]
     last_end = 0
     for s, e, term, w, quote in candidates:
@@ -494,7 +633,7 @@ def score_text(text, data, formal=False):
         hits.append({"cat": "lexicon", "name": term, "w": w, "quote": quote})
     riders, triggers = data.get("riders", {}), data.get("rider_triggers", [])
     if riders:
-        for (a, _), sent in zip(sent_spans, sents):
+        for (a, _), sent in zip(sent_spans, scan_sents):
             sl = sent.lower()
             if not any(t in sl for t in triggers):
                 continue
@@ -1081,14 +1220,15 @@ def facts(text, _other=""):
     out = {}
     for kind, rx in FACT_RX:
         found = set()
-        for m in re.finditer(rx, urls if kind == "url" else prose):
+        flags = re.I if kind == "figure" else 0
+        for m in re.finditer(rx, urls if kind == "url" else prose, flags):
             v = (m.group(1) if m.lastindex else m.group(0)).strip()
             if kind == "name":
                 v = _peel_entity(v, prose, other)
                 if not v:
                     continue
             if kind == "figure":
-                v = v.replace(",", "").lstrip("$").rstrip()
+                v = v.replace(",", "").lstrip("$").rstrip().lower()
                 v = re.sub(r"\s*percent$", "%", v)
                 v = re.sub(r"\s*(million|bn|billion|m|k)$",
                            lambda x: {"million":"m","billion":"bn"}.get(x.group(1), x.group(1)), v)
@@ -1156,7 +1296,9 @@ BLOCKQUOTE_LINE_RX = re.compile(r"^[ \t]*>[^\n]*$", re.M)
 HEADING_RX = re.compile(r"^(#{1,6})[ \t]+(.+?)[ \t]*$", re.M)
 PATH_RX = re.compile(
     r"(?<![\w:])((?:\.\.?/|/)[A-Za-z0-9._~\-]+"
-    r"(?:/[A-Za-z0-9._~\-]+)*|[A-Za-z]:\\[A-Za-z0-9._\\~\-]+)"
+    r"(?:/[A-Za-z0-9._~\-]+)*|(?:[A-Za-z0-9._~\-]+/)+"
+    r"[A-Za-z0-9._~\-]+\.[A-Za-z0-9._~\-]+|"
+    r"[A-Za-z]:\\[A-Za-z0-9._\\~\-]+)"
 )
 
 
@@ -1318,6 +1460,49 @@ def figure_contexts(text, figures):
     return out
 
 
+def load_adjudication(path, original):
+    """Load explicit dropped-figure rulings bound to one exact source text.
+
+    The file is intentionally small and closed-schema. It cannot weaken name,
+    quote, URL, feeling, or structure checks, and it cannot excuse a number that
+    was not present in the source it names.
+    """
+    source = Path(path)
+    try:
+        if source.stat().st_size > 65_536:
+            raise ValueError("adjudication file exceeds 64 KiB")
+        payload = json.loads(source.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"cannot read adjudication file: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise ValueError("adjudication file must be a JSON object")
+    expected = {"schema", "original_sha256", "allow_dropped_figures"}
+    if set(payload) != expected or payload.get("schema") != 1:
+        raise ValueError("adjudication file must use schema 1 and only documented keys")
+    digest = payload.get("original_sha256")
+    actual = hashlib.sha256(original.encode("utf-8")).hexdigest()
+    if not isinstance(digest, str) or digest != actual:
+        raise ValueError("adjudication source hash does not match the original text")
+    raw = payload.get("allow_dropped_figures")
+    if not isinstance(raw, list) or len(raw) > 100:
+        raise ValueError("allow_dropped_figures must be a list of at most 100 figures")
+    original_figures = facts(original)["figure"]
+    allowed = []
+    for item in raw:
+        if not isinstance(item, str) or not item.strip() or len(item) > 80:
+            raise ValueError("each allowed figure must be a short non-empty string")
+        parsed = facts(item)["figure"]
+        if len(parsed) != 1:
+            raise ValueError(f"allowed figure is not one unambiguous figure: {item!r}")
+        canonical = next(iter(parsed))
+        if canonical not in original_figures:
+            raise ValueError(f"allowed figure is absent from the original: {item!r}")
+        allowed.append(canonical)
+    if len(allowed) != len(set(allowed)):
+        raise ValueError("allow_dropped_figures contains a duplicate")
+    return set(allowed)
+
+
 def fidelity(before, after, adjudicated=None):
     """Did the rewrite keep every fact, and did it add any?
 
@@ -1500,8 +1685,8 @@ def rewrite_score(before_text, after_text, genre=None, data=None,
             "preserved": fid["preserved"], "invented": fid["invented"]}
 
 
-def render_fidelity(before, after):
-    r = fidelity(before, after)
+def render_fidelity(before, after, adjudicated=None):
+    r = fidelity(before, after, adjudicated)
     out = ["", "  FACT AND MEANING CHECK · original vs edited text", ""]
     for kind, kept, dropped, added in r["rows"]:
         out.append(f"  {kind:<8} {len(kept)} kept"
@@ -1520,6 +1705,9 @@ def render_fidelity(before, after):
         out.append("  protected document content changed:")
         for finding in r["structure"][:8]:
             out.append(f"           {finding['code']:<23} {finding['message']}")
+    if r.get("unsourced"):
+        for figure in sorted(r["unsourced"]):
+            out.append(f"  ruled cut {figure!r} (reviewer marked it unsourced)")
     out += ["",
             "  Result: " + ("facts preserved; nothing added"
                              if r["preserved"] and not r["invented"] else
@@ -1606,7 +1794,7 @@ def main():
     if "--help" in argv or "-h" in argv:
         print(__doc__)
         return 0
-    value_flags = {"--gate", "--genre", "--voice"}
+    value_flags = {"--gate", "--genre", "--voice", "--adjudication"}
     bool_flags = {"--json", "--explain", "--formal", "--fidelity", "--dna",
                   "--portfolio", "--batch", "--heatmap"}
     unknown = [arg for arg in argv if arg.startswith("--")
@@ -1619,6 +1807,8 @@ def main():
              if flag in argv]
     if len(modes) > 1:
         raise SystemExit("choose only one mode: " + ", ".join(modes))
+    if "--adjudication" in argv and "--fidelity" not in argv:
+        raise SystemExit("--adjudication is valid only with --fidelity")
 
     gv, _ = gate_value()
     # Values that belong to a flag (--gate 25, --genre social, --voice manav)
@@ -1653,9 +1843,16 @@ def main():
         if len(args) != 2:
             sys.exit("--fidelity needs exactly two files: before and after")
         before, after = _read_text_file(args[0]), _read_text_file(args[1])
-        for line in render_fidelity(before, after):
+        adjudicated = None
+        ruling_path = _required_option_value(argv, "--adjudication")
+        if ruling_path:
+            try:
+                adjudicated = load_adjudication(ruling_path, before)
+            except ValueError as exc:
+                raise SystemExit(str(exc)) from exc
+        for line in render_fidelity(before, after, adjudicated):
             print(line)
-        r = fidelity(before, after)
+        r = fidelity(before, after, adjudicated)
         sys.exit(0 if (r["preserved"] and not r["invented"]) else 1)
 
     if "--dna" in sys.argv:
@@ -1787,6 +1984,11 @@ def main():
               f"layout; your AI assistant still reviews the ideas, voice, and facts.")
         sys.exit(0 if ok else 1)
 
+    # Last line of a human run, and only ever once. See record_human_run.
+    note = record_human_run()
+    if note:
+        print(note, file=sys.stderr)
+
 
 if __name__ == "__main__":
     main()