zero-slop 2.7.7 → 2.8.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Manav Mishra
+Copyright (c) 2026 Garage Capital Ventures
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,20 +5,70 @@
   <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.7-72528F">
+  <img alt="version" src="https://img.shields.io/badge/version-2.8.0-72528F">
+  <a href="https://hol.org/guard/plugins"><img alt="Listed in the HOL plugin registry" src="https://img.shields.io/badge/HOL%20registry-listed-2C6E8F"></a>
+  <a href="https://github.com/hashgraph-online/awesome-ai-plugins#tools--integrations"><img alt="Listed in awesome-ai-plugins" src="https://img.shields.io/badge/awesome--ai--plugins-listed-2C6E8F"></a>
+  <a href="https://zero-slop.ai/try/"><img alt="This README scores 12.0 out of 100 on the slop score, inside the human range" src="https://img.shields.io/badge/slop%20score-12.0%2F100-0f7d55"></a>
 </p>
 
-Take all the slop out of your AI writing. The #1 agentic anti-slop skill.
+Less slop, more pop in your writing.
 
-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 or agent harness an editing workflow on guardrails. Its
+MIT-licensed local checks run offline; your existing AI assistant or harness does the editing.
+Score a draft at [zero-slop.ai/try](https://zero-slop.ai/try/); benchmark at
+[zero-slop.ai](https://zero-slop.ai).
 
-![A scored sentence before and after editing](assets/demo.png)
+```sh
+npx zero-slop install
+```
+
+![Scoring a launch post at 100.0, rewriting it to 9.5, with the 40% figure held by the fact gate](assets/zero-slop-demo.gif)
+
+### What it does, on a real draft
+
+A launch post, as AI wrote it:
+
+> We're thrilled to announce that our team has leveraged cutting-edge AI to deliver a seamless onboarding experience. It's not just a redesign, it's a fundamental reimagining of how users engage with our platform. In today's fast-paced landscape, the ability to iterate quickly is crucial. By harnessing the power of machine learning, we've been able to reduce setup time by 40%. Here's the thing nobody tells you: onboarding is where most products lose their users. We're excited to continue this journey with you.
+
+`slopscore.py --explain` on that paragraph, unedited:
+
+```text
+Writing score: 100.0/100  [major rewrite]
+  Flagged phrases : 11 across 83 words
+  Sentence variety: too even
+  Main issues     : canned LinkedIn phrase, promotional language, manufactured
+                    stakes, two-part contrast used as a formula, performed
+                    writer's voice, buzzword used as promotion
+
+  Flagged phrases (11), strongest first:
+    "In today's fast-paced"  manufactured stakes; start where the reader needs to start
+    "We're thrilled to"      canned LinkedIn phrase; say what happened without the stock opening
+    "It's not just a redesign, it's"
+                             two-part contrast used as a formula; state the claim once, plainly
+    "Here's the thing"       performed writer's voice; say the thing plainly
+    'cutting-edge'           promotional language; name what it does; cut the adjectives
+    'leveraged'              buzzword used as promotion; use the plain word
+```
+
+The rewrite, limited to the draft's stated claims:
+
+> We used machine learning to reduce onboarding setup time by 40%.
+
+```text
+Writing score: 9.5/100  [clear]
+  Flagged phrases : 0 across 10 words
+```
 
 ## 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 emdash is fine. Multiple emdashes, definitely slop. The same effect can come from repetition in the wording or the structure. Mechanical rhythm and overworked formatting can do it too.
 
-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
 
@@ -34,7 +84,10 @@ Or install it with `npx`:
 npx skills add manavmishra/ZeroSlop --global
 ```
 
-Or from the registry, which also installs the scorer as a command:
+Or from the registry, which also installs the scorer as a command. Zero Slop is
+listed in [awesome-ai-plugins](https://github.com/hashgraph-online/awesome-ai-plugins#tools--integrations)
+and carries a public profile in the [HOL plugin registry](https://hol.org/guard/plugins),
+where its trust score and scanner results are published:
 
 ```sh
 npx zero-slop install          # add --harness codex|cursor|opencode|zed
@@ -42,7 +95,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 +104,21 @@ 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.
+
+## Show your score
+
+The badge above is this README's own, from `npx zero-slop score README.md`.
+Put yours up the same way:
+
+```md
+[![Slop score](https://img.shields.io/badge/slop%20score-12.0%2F100-0f7d55)](https://zero-slop.ai/try/)
+```
+
+Colours are the scorer's bands: `0f7d55` under 25, `b8860b` under 60, `b0502c`
+above.
 
 ## The slop that Zero Slop catches
 
@@ -68,9 +135,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).
@@ -84,7 +151,7 @@ Eight roles form one workflow. Each is a job rather than a service, run as its o
 
 | Role | Who does it | What happens |
 |---|---|---|
-| 1. Scorer | Local tools | Finds the exact wording, rhythm, readability, and formatting problems that raised the writing score. |
+| 1. Scorer | Local tools | Finds the exact phrases behind the writing score, then checks pacing and readability. It also catches overworked formatting. |
 | 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. |
@@ -101,15 +168,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 +185,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 +218,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.7 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 3.51% 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 1.86% lower median throughput across 31 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 +254,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.7"
+  version: "2.8.0"
   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.7",
-  "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.8.0",
+  "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"
   },
@@ -50,6 +50,7 @@
     "!scripts/contextual.py",
     "!scripts/contextual-signals.md",
     "!references/contextual-signals.md",
+    "!scripts/make-readme-gif.mjs",
     "!scripts/growth-snapshot.mjs",
     "!data/voices/",
     "!**/__pycache__/"

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

@@ -35,6 +35,7 @@ import sys
 # certified-human samples would let these budgets be derived rather than argued.
 MIN_WORDS = 300
 BUDGETS = {
+    "antithesis_pair": (0.0, 2),
     "subtractive_contrast": (6.0, 3),
     "comma_series": (26.0, 8),
     "significance_scaffolding": (0.0, 1),
@@ -51,6 +52,90 @@ 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,
+}
+
+# eval.md A1 / SKILL.md step 2.1: antithesis pairs -- two balanced statements,
+# the second landing the twist. Budget is ONE per piece, and "three or more under
+# 500 words means the register failed whatever the score said."
+#
+# This report had no row for that family. RX_SUBTRACTIVE below is a different
+# check -- eval.md A2, the corrective appositive, judged on density -- and it was
+# carrying the whole contrast family's name in the report while A1 went
+# unmeasured. A 479-word manifesto with five antithesis pairs in it therefore
+# printed "Binary contrasts: 1 found, ok" and nothing else about contrast.
+#
+# Two of the four shapes are reachable without a parser, and only those two ship:
+#   marked staccato   -- "Not perfect. Honest."
+#   adjacent isocolon -- one verb frame, both arguments swapped: "Speed is moving
+#                        fast. Velocity is moving fast in the same direction."
+# Bare subject swap and unmarked reversal stay the reader's judgment, exactly as
+# references/tells.md already says they must.
+ANTITHESIS_STOP = frozenset("""
+a an the this that these those it its is are was were be been being am do does did
+to of in on at by for with from as and or but so if then than not no nor yet
+we you they he she i us our your their his her them me my their there here
+one two three first second next last own same very just only also more most less
+""".split())
+
+# The negation can open the pair ("Not perfect. Honest.") or land at the end of
+# it ("The draft was cheap. The signal it sent was not."). Both are in tells.md.
+RX_MARKED_OPEN = re.compile(r"^\W*not\b", re.I)
+RX_MARKED_CLOSE = re.compile(r"\b(?:was|were|is|are|did|does|do|has|have|had|will)\s+not\W*$", re.I)
+
+
+def _antithesis_content(sent: str) -> list[str]:
+    """Content words, with a trailing -s folded away so a verb frame still
+    matches when only its agreement changed: 'let' and 'lets' are one frame."""
+    out = []
+    for word in re.findall(r"[A-Za-z][\w'-]*", sent):
+        word = word.lower()
+        if word in ANTITHESIS_STOP:
+            continue
+        if len(word) > 3 and word.endswith("s") and not word.endswith("ss"):
+            word = word[:-1]
+        out.append(word)
+    return out
+
+
+def antithesis_pairs(prose: str) -> list[str]:
+    """Adjacent balanced sentences: the marked form, and the swapped-argument one."""
+    out = []
+    sents = _sentences(prose)
+    for first, second in zip(sents, sents[1:]):
+        n_first, n_second = len(first.split()), len(second.split())
+        # Both halves have to be short enough to read as one figure. A short
+        # line beside a paragraph-length sentence is not a balanced pair.
+        if not (2 <= n_first <= 14 and 1 <= n_second <= 14):
+            continue
+        # Marked: the twist is announced, at either end of the pair.
+        if RX_MARKED_OPEN.match(first) and n_second <= 10:
+            out.append(f"{first} {second}")
+            continue
+        if RX_MARKED_CLOSE.search(second) and n_first <= 10:
+            out.append(f"{first} {second}")
+            continue
+        head, tail = _antithesis_content(first), _antithesis_content(second)
+        if len(head) < 2 or len(tail) < 2:
+            continue
+        # Identical content is repetition, not antithesis: the figure needs the
+        # arguments to have changed.
+        if head == tail:
+            continue
+        shared = set(head) & set(tail)
+        # A shared frame carrying most of the shorter sentence, with the
+        # arguments changed: that is the figure, not an accidental echo.
+        if len(shared) >= 2 and len(shared) / min(len(head), len(tail)) >= 0.5:
+            out.append(f"{first} {second}")
+    return out
+
 
 # "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.
@@ -133,6 +218,28 @@ RX_INFLATION = re.compile(
     r"(?:improvement|progress|difference|impact|result|results|value|win|shift"
     r"|change|benefit|breakthrough|game.?changer)\b", re.I)
 
+# An imperative is the bare base form, so it carries none of the inflection
+# (-s, -ed, -es) or the auxiliaries FINITE_VERB looks for: "Play to win." and
+# "Build durable growth." were both being reported as verbless fragments. On the
+# seven-line manifesto that surfaced this, two of the five hits were imperatives,
+# so 40% of the document's one finding was wrong. A closed list is the same
+# device FINITE_VERB already is, and it only ever fires at a sentence opening.
+IMPERATIVE_OPENER = re.compile(
+    r"^\W*(?:and|but|so|then|now|first|next|finally)?\W*"
+    r"(?:add|aim|allow|apply|ask|assume|avoid|begin|book|break|bring|build|buy"
+    r"|call|change|check|choose|clean|clear|click|close|collect|come|compare"
+    r"|consider|copy|count|cover|create|cut|decide|define|delete|deliver|design"
+    r"|do|draw|drive|drop|edit|enter|expect|explain|fill|find|finish|fix|focus"
+    r"|follow|forget|get|give|go|grab|grow|handle|help|hire|hold|imagine|include"
+    r"|install|invest|join|keep|know|launch|lead|learn|leave|let|listen|look"
+    r"|love|make|meet|move|name|note|notice|open|pay|pick|plan|play|point|prefer"
+    r"|press|pull|push|put|read|remember|remove|repeat|replace|report|reset"
+    r"|return|review|run|save|say|scale|see|select|sell|send|set|share|ship|show"
+    r"|sign|skip|solve|sort|speak|spend|stand|start|stay|stop|study|take|talk"
+    r"|teach|tell|test|think|throw|touch|track|treat|trust|try|turn|update|use"
+    r"|wait|walk|want|watch|win|write)\b",
+    re.I)
+
 FINITE_VERB = re.compile(
     r"\b(?:is|are|was|were|be|been|being|has|have|had|do|does|did|can|could|will"
     r"|would|shall|should|may|might|must|gets?|goes|comes?|makes?|takes?|gives?"
@@ -152,6 +259,8 @@ def verbless_fragments(prose: str) -> list[str]:
             continue
         if sent.rstrip().endswith(":") or sent.lstrip().startswith(("-", "*", "#", "|")):
             continue
+        if IMPERATIVE_OPENER.match(sent):
+            continue
         if not FINITE_VERB.search(sent):
             out.append(sent)
     return out
@@ -287,7 +396,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
@@ -298,9 +407,10 @@ def measure(text: str) -> dict:
     triads = [" ".join(m.group(0).split()) for m in NEGATION_TRIAD.finditer(prose)]
     dangling = dangling_pointers(text)
     fragments = verbless_fragments(prose)
+    antithesis = antithesis_pairs(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 +421,15 @@ 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},
+        "antithesis_pair": {"count": len(antithesis), "per_1k": per_k(len(antithesis)), "hits": antithesis[:6]},
         "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 +440,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
 
@@ -342,7 +456,8 @@ LABEL = {
     "verbless_fragment": "Verbless fragments",
     "thin_section": "Headings over a sentence or two",
     "referent_cluster": "One thing under several names",
-    "subtractive_contrast": "Binary contrasts",
+    "antithesis_pair": "Antithesis pairs",
+    "subtractive_contrast": "Binary contrasts (X, not Y)",
     "comma_series": "Comma-series density",
     "significance_scaffolding": "Announced significance",
     "classifier_scaffolding": "Graded not delivered (stems)",
@@ -360,8 +475,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 +618,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 +665,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 +703,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 +736,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 +751,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 +812,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")
 
 
@@ -77,13 +91,10 @@ def _load_notes():
 
 def _save_notes(state):
     try:
-        HOME.mkdir(parents=True, exist_ok=True)
-        tmp = NOTES_FILE.with_suffix(".json.tmp")
-        with open(tmp, "w", encoding="utf-8") as fh:
-            json.dump(state, fh)
-        os.replace(tmp, NOTES_FILE)
+        atomic_write_text(NOTES_FILE, json.dumps(state) + "\n", mode=0o600)
+        return True
     except OSError:
-        pass  # a read-only home must never break a score
+        return False  # a read-only home must never break a score
 
 
 def star_note_is_due(argv=None, isatty=None, env=None):
@@ -112,14 +123,22 @@ def record_human_run(argv=None, isatty=None, env=None):
         return None
     if not (sys.stdout.isatty() if isatty is None else isatty):
         return None
-    state = _load_notes()
-    if state.get("star_note_shown"):
+    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
-    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
-    _save_notes(state)
     if not due:
         return None
     return ("\n  If Zero Slop has been useful, a star helps people find it: "
@@ -1201,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)
@@ -1276,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._\\~\-]+)"
 )
 
 
@@ -1438,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?
 
@@ -1620,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"
@@ -1640,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
@@ -1726,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("--")
@@ -1739,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)
@@ -1773,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: