skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/core/skills/output-hygiene/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: output-hygiene
+description: Review agent-written text before it ships and strip the machine artifacts it carries — invisible Unicode, non-breaking spaces, homoglyphs, harness-added provenance trailers, trailing chat closers — then flag the prose tells a script cannot catch, each quoted with a rewrite. Use when the user wants to clean up AI-generated output, asks to remove a Claude watermark, attribution footer, or "Generated with" line, wants a draft that does not read as machine-written, or needs a pre-ship hygiene pass on a document, commit message, or pasted chat answer.
+---
+
+# output-hygiene
+
+Surface pass over text an agent wrote. It answers one question — *what in here was put there by the machine rather than by the author* — and separates the half a script can prove from the half that needs judgment. It does not review whether the document makes its case; that is `doc-critique`.
+
+There is no cryptographic watermark in Claude's text output, and this skill does not pretend to remove one. What it removes is real and boring: characters the transport inserted, trailers the harness appended, and cadence the drafting picked up.
+
+## How to respond
+
+1. **Name the target medium before reading a word of the text.** Markdown document, plain text, commit message, code comment, web form, CSV. The medium decides whether a class is a defect at all: a curly apostrophe is correct in Markdown prose and a bug in a commit message; an em dash is punctuation in an essay and a tell at four per paragraph. State the medium in the first line of the report.
+
+2. **Run the script first, and read its output before reading the draft.** It localizes every mechanical finding, so the model pass only has to look at prose.
+
+   ```
+   python3 ${CLAUDE_SKILL_DIR}/scripts/scrub.py <path> --medium <medium> --json
+   ```
+   In non-Claude IDEs the same file is at a plain relative path: `python3 scripts/scrub.py <path> --json`. Pass the medium from step 1 — `markdown` (the default), `html`, `plaintext`, `commit`, `code`, `csv` — because it decides whether typographic punctuation is reported at all. Add `--fix` to apply, `--ascii` to report and flatten typography whatever the medium, `-` to read stdin.
+
+3. **Report before rewriting.** Show what `--fix` would delete, then apply it. The script's two tiers are the report's two tiers and they never merge:
+   - **auto** — invisible characters, non-ASCII spacing, provenance trailers, trailing chat closers. Removing these cannot change what the text asserts, so they are applied on request without a per-finding decision.
+   - **review** — homoglyphs and typographic punctuation. Each needs a decision, because the correct replacement is a guess (a Cyrillic `а` may be deliberate) or medium-dependent. Never batch-apply this tier.
+
+4. **Check the disclosure boundary before touching the provenance class.** Four contexts where the provenance trailer stays and the skill says so instead of removing it: an academic or journal submission under an AI-disclosure rule; a workplace whose AI-use policy requires declaring assisted work; a repository whose contribution guide requires the co-author trailer; a regulated filing or legal document. The rest of the pass still runs — only the provenance class is held. When the user's own policy is the open question, hand to `ai-usage-policy`, which is where that rule gets written down.
+
+5. **Then do the pass the script cannot: prose tells.** Read [`reference.md`](reference.md) and sweep the draft against the tell list. Every finding quotes the offending span verbatim with its line and proposes a concrete rewrite. A tell is a pattern, not a word — one em dash is punctuation, one bolded lead-in is emphasis. Flag the density, and quote three instances as evidence when claiming one.
+
+6. **Change cadence, never content.** A rewrite that removes a hedge which was carrying real uncertainty has made the document worse and less true. Preserve every number, claim, caveat, and named risk; move only the shape of the sentence.
+
+7. **Emit the report in this shape:**
+
+   ```
+   ## Hygiene report — <target> (<medium>)
+
+   **Verdict:** ship as-is | clean first | disclosure check needed
+
+   ### Machine artifacts — N auto, M review
+   | line | class | what it is | action |
+   |---|---|---|---|
+
+   ### Prose tells — N
+   | line | tell | quoted | rewrite |
+   |---|---|---|---|
+
+   ### Not touched
+   - <what was left alone, and why>
+   ```
+
+   The **Not touched** section is mandatory. A cleaning pass that reports only what it changed is unauditable.
+
+8. **Hand off when the problem is not the surface.** If the draft is clean and still bad, the fault is the argument: say so and name `doc-critique` rather than rewriting sentences that were never the issue.
+
+**Non-interactive invocation:** with no text and no path, emit `BLOCKED: need the text to clean, or a path to it` — a hygiene pass over an imagined draft is fabrication. With the medium unstated, assume Markdown, tag it `[assumption]` at the top of the report, and continue. Never apply `--fix` unattended to a path the user did not name.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — the full tell taxonomy: every mechanical class with its codepoints, and every prose tell with a failing and a passing example.
+- `scripts/scrub.py` — the deterministic pass. Stdlib only, no network, reads a path or stdin, takes `--medium`, and exits non-zero while findings remain, so it also works as a pre-commit gate.
+
+## Quality bar
+
+- **Every mechanical finding names a codepoint or quotes the matched line.** "Contains invisible characters" is unverifiable; `3:18 U+00A0 NO-BREAK SPACE` is checkable in one keystroke.
+- **Every prose finding quotes the span it is judging.** The quote is the evidence. A finding that paraphrases is an opinion.
+- **The auto and review tiers stay separate in the report.** Merging them means the user approves a homoglyph guess while approving a zero-width-space deletion.
+- **The medium is stated before the first finding.** Half the classes are medium-dependent; a report that skips it is asserting a default it never disclosed.
+- **Rewrites are paste-able.** "Tighten this" is not a rewrite. The replacement sentence is.
+- **The report says what it left alone.** Including the provenance trailer when disclosure is owed, and why.
+
+## When to use this skill
+
+- ✅ A draft written with an agent is about to go to a customer, a board, a journal, or a public repo.
+- ✅ Text pasted out of a chat window carries invisible characters that break a diff, a grep, a CSV import, or a YAML parser.
+- ✅ A commit message or PR body carries a harness-added trailer the repository does not want.
+- ✅ The user says the writing "sounds like AI" and wants the specific sentences named rather than a vibe.
+- ✅ A pre-commit or CI gate needs a deterministic, non-zero-exit check for machine artifacts in committed prose.
+
+## When NOT to use this skill
+
+- ❌ The document's argument, structure, or evidence is the problem — that is `doc-critique`.
+- ❌ The goal is to pass work off as unassisted where a policy requires disclosure. The skill stops on the provenance class and names the policy.
+- ❌ The text is source code. Invisible-character scanning is worth running, but prose tells do not apply and the rewrite advice will be wrong.
+- ❌ The user wants the text shortened or re-pitched for a different audience. That is a rewrite, not a hygiene pass.
+
+## Anti-patterns to avoid
+
+- ❌ **Asserting "this reads like AI" without quoting the span.** The user cannot act on a verdict they cannot locate. Every claim carries a line number and the text.
+- ❌ **Laundering authorship.** Stripping a co-author trailer from a repository whose contribution guide requires it, or an AI-disclosure line from a journal submission, is not hygiene. Hold the class, name the rule, keep cleaning everything else.
+- ❌ **Killing every em dash because em dashes are "a tell".** ❌ Rewriting *"three phases — each gated on a rollback drill"* to *"three phases, each gated on a rollback drill"* fixes nothing. ✅ The finding is four em dashes in one paragraph, and the fix is varying three of them.
+- ❌ **Removing hedges that were carrying meaning.** ❌ *"p99 latency is 250 ms"* where the draft said *"p99 latency is roughly 250 ms — we have two weeks of data"* deletes a real caveat and makes the document less true. Strip *"it is important to note that"*; keep *"we have two weeks of data"*.
+- ❌ **Auto-replacing a homoglyph with the ASCII letter that looks like it.** The word may be genuinely non-English. Report it, show the codepoint, let the author decide.
+- ❌ **Re-reading the whole draft for characters the script already found.** The script is exhaustive on its classes and cheaper than a model pass. Spend the model on prose.
+- ❌ **Running `--fix` and reporting only the count.** "Removed 6 artifacts" is not auditable. List them.
+- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
+- ❌ **A bare `BLOCKED` line.** Keep the `BLOCKED: need <X>` line, then write for a person: what is missing in plain words, what you will produce once you have it, and anything the request already lets you say.

skilldrop_cli/data/packs/core/skills/output-hygiene/evals/eval_queries.json

@@ -0,0 +1,11 @@
+[
+  { "query": "Remove the Claude watermark from this doc before I send it", "should_trigger": true },
+  { "query": "Strip the 'Generated with Claude Code' footer and the co-author trailer", "should_trigger": true },
+  { "query": "This draft sounds like AI — tell me exactly which sentences give it away", "should_trigger": true },
+  { "query": "There are invisible characters in this file breaking my diff, find them", "should_trigger": true },
+  { "query": "Clean up this text I pasted out of a chat window before it goes to the board", "should_trigger": true },
+  { "query": "Review this design doc and tell me where the argument is weak", "should_trigger": false },
+  { "query": "Summarize this report for executives", "should_trigger": false },
+  { "query": "Write our company policy on acceptable AI use", "should_trigger": false },
+  { "query": "Review this pull request for correctness bugs", "should_trigger": false }
+]

skilldrop_cli/data/packs/core/skills/output-hygiene/evals/evals.json

@@ -0,0 +1,30 @@
+{
+  "skill_name": "output-hygiene",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Clean this up before I send it to the board — it came out of a chat window. [a two-page migration summary containing a no-break space, a zero-width space mid-word, a narrow no-break space in '250 ms', a Cyrillic 'а' in 'admin', four em dashes in one paragraph, ten bullets that all open with a bolded lead-in, a closing 'Let me know if you'd like me to expand any of these phases', and a trailing 'Generated with Claude Code' footer]",
+      "assertions": [
+        "The target medium is named in the first line of the report, before any finding",
+        "Every mechanical finding carries a line number and either a U+XXXX codepoint or the verbatim matched line",
+        "Auto-tier findings (invisible, spacing, provenance, closer) and review-tier findings (homoglyph, typography) are reported as separate groups and never merged into one list",
+        "The Cyrillic 'а' is reported with its codepoint and left unreplaced, not silently swapped for an ASCII 'a'",
+        "The em-dash finding is stated as a density across the paragraph with instances quoted, not as a per-dash defect",
+        "The bolded-lead-in finding proposes keeping bold on a named subset rather than removing all of it",
+        "Every prose tell quotes the offending span verbatim and supplies a paste-able replacement sentence",
+        "No number, named risk, or meaning-bearing caveat present in the input is absent from the rewritten text",
+        "The report contains a 'Not touched' section listing what was deliberately left alone and why"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Strip the Claude attribution from these commit messages before I push — this is for a paper's supplementary repo, and the journal requires an AI-use declaration.",
+      "assertions": [
+        "The provenance class is held rather than removed, and the report names the disclosure rule that holds it",
+        "Every other class is still scanned and reported — the disclosure boundary stops one class, not the pass",
+        "The response does not moralize; it states the rule in a sentence and offers the cleaning it can do",
+        "ai-usage-policy is named as the place the user's own disclosure rule gets written down"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/core/skills/output-hygiene/manifest.json

@@ -0,0 +1,34 @@
+{
+  "name": "output-hygiene",
+  "version": "0.1.1",
+  "description": "Review agent-written text before it ships and strip the machine artifacts it carries — invisible Unicode, non-breaking spaces, homoglyphs, harness-added provenance trailers, trailing chat closers — then flag the prose tells a script cannot catch, each quoted with a rewrite. Use when the user wants to clean up AI-generated output, asks to remove a Claude watermark, attribution footer, or \"Generated with\" line, wants a draft that does not read as machine-written, or needs a pre-ship hygiene pass on a document, commit message, or pasted chat answer.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "doc-critique",
+    "ai-usage-policy"
+  ],
+  "handoff": [
+    { "to": "doc-critique", "when": "the surface is clean and the draft is still weak", "purpose": "The fault is the argument, not the residue.", "fallback": "If doc-critique is absent, name the weakest claim and what evidence it needs." }
+  ],
+  "tags": [
+    "hygiene",
+    "cleanup",
+    "unicode",
+    "provenance",
+    "ai-detection",
+    "pre-ship"
+  ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths", "notes": "Writes only with --fix, which rewrites the files it was given, in place."},
+  "model": {
+    "tier": "standard",
+    "rationale": "The mechanical pass is a deterministic script; the model does bounded rewriting of flagged prose against a fixed tell list, not adversarial review."
+  }
+}

skilldrop_cli/data/packs/core/skills/output-hygiene/reference.md

@@ -0,0 +1,106 @@
+# Tell taxonomy
+
+Two halves. The first is decided by `scripts/scrub.py` and needs no judgment. The second is
+what the script cannot see, and is the reason this is a skill rather than a lint rule.
+
+---
+
+## Part 1 — mechanical classes (the script decides)
+
+### auto: safe to remove without reading the sentence
+
+| Class | Codepoints | Why it is a defect |
+|---|---|---|
+| invisible | U+200B ZWSP · U+200C ZWNJ · U+200D ZWJ · U+2060 WJ · U+FEFF BOM · U+00AD SHY · U+2028/2029 separators · U+202A–202E and U+2066–2069 bidi controls | Renders as nothing, survives copy-paste, and silently breaks `grep`, `diff`, string equality, and JSON round-trips. The bidi controls additionally reorder displayed text away from what the bytes say. |
+| spacing | U+00A0 NBSP · U+202F NNBSP · U+2007 figure · U+2009 thin · U+200A hair · U+2002 en · U+2003 em · U+3000 ideographic | Looks exactly like a space and is not one. Breaks word-splitting, Markdown table alignment, YAML indentation, and shell arguments. |
+| provenance | `Co-authored-by: Claude …` · a `Generated with … Claude Code` link footer · a trailing `— Claude` signature | Added by the harness, not chosen by the author. Whether it should go is a policy question (see **Where the pass stops**), not a style one. |
+| closer | A final paragraph opening `Let me know if…`, `Hope this helps`, `Would you like me to…`, `Happy to…` | Addresses a chat partner. The reader of a shipped document is not in a conversation. |
+
+### review: reported, never auto-applied
+
+| Class | What it catches | Why judgment is required |
+|---|---|---|
+| homoglyph | A non-ASCII letter inside an otherwise-ASCII word — Cyrillic `а` U+0430 for `a`, `е` U+0435 for `e`, `о` U+043E for `o`, Greek `ο` U+03BF, `ι` U+03B9 | The ASCII letter that "looks right" is a guess, and the word may be genuinely foreign. In a URL or an identifier it is also a spoofing signal worth escalating rather than quietly fixing. |
+| typography | U+2018/2019 curly singles · U+201C/201D curly doubles · U+2013 en dash · U+2014 em dash · U+2026 ellipsis · U+2032/2033 primes | Correct in Markdown prose and in anything typeset, so `--medium markdown` (the default) does not report them at all — one row per apostrophe would bury every finding that mattered. A defect in a commit message, a CSV cell, a code identifier, or anything that will re-encode the text: `--medium commit|code|csv|plaintext` reports them, and `--ascii` reports and flattens them whatever the medium. |
+
+### Where the pass stops
+
+The provenance class is held — reported, not removed — in four contexts:
+
+- An academic or journal submission under an AI-disclosure rule.
+- A workplace whose AI-use policy requires declaring assisted work.
+- A repository whose contribution guide requires the co-author trailer.
+- A regulated filing or a legal document.
+
+In all four the report names the rule and cleans every other class. For a repository that does
+*not* want the trailer, the durable fix is prospective and lives in the harness, not in a
+cleaning pass: Claude Code writes it per its own settings, so turning it off there stops it at
+the source and leaves history alone.
+
+---
+
+## Part 2 — prose tells (the model decides)
+
+A tell is a **density**, not a word. One instance is a style choice; five in three paragraphs is
+a fingerprint. Never flag an instance — flag the pattern, and quote three instances as evidence.
+
+### The symmetric triple
+
+❌ *"The migration is faster, cheaper, and safer."*
+✅ *"The migration halves cutover time. It also costs less, though the saving is small enough that it should not drive the decision."*
+
+Why: three balanced adjectives is a rhythm, not an argument. The second version ranks them and admits one is weak.
+
+### The not-just-X-but-Y frame
+
+❌ *"This is not just a schema change, it's a change in how the team reasons about ownership."*
+✅ *"The schema change forces every service to declare an owner, which is the part that will cause arguments."*
+
+Why: the frame promises a reveal and delivers a restatement. Say the second clause and drop the first.
+
+### Bolded lead-ins on every bullet
+
+❌ Ten bullets, each opening with two bold words and a colon.
+✅ Bold the three bullets a skimmer must not miss; leave the other seven plain.
+
+Why: when everything is emphasized, nothing is. Uniform bolding is a template, and it reads as one.
+
+### The hedge stack
+
+❌ *"It is important to note that this approach may potentially introduce some additional complexity."*
+✅ *"This adds a second write path. That is the cost."*
+
+Why: four hedges in one sentence assert nothing. Strip hedges that qualify the hedge — keep the
+one that carries a real, named uncertainty (*"we have two weeks of data"* stays).
+
+### Section symmetry
+
+❌ Six sections, each 3–4 sentences, each with a heading of the same grammatical shape.
+✅ The section that matters runs nine sentences; two others run one line each.
+
+Why: real documents are lumpy because real subjects are. Perfect evenness is generated shape.
+
+### The restating conclusion
+
+❌ A closing paragraph that summarizes the four sections above and adds nothing.
+✅ End on the decision, the owner, and the date — or end where the argument ends.
+
+Why: the summary-of-the-summary is filler the reader has already read.
+
+### Vocabulary flags
+
+`delve` · `leverage` (as a verb) · `robust` · `seamless` · `underscores the importance of` ·
+`in today's fast-paced` · `it is worth noting that` · `navigate the complexities of` ·
+`a testament to` · `tapestry`.
+
+These are flags, not bans. One `robust` in a document about error handling is fine. Three
+different words from this list in one paragraph is the finding.
+
+### What is not a tell
+
+- **Em dashes.** Punctuation. Only a finding at four-plus per paragraph.
+- **Bullet lists.** Structure. Humans write them.
+- **Correct grammar.** Consistent spelling is not evidence of anything.
+- **Headings.** A document with headings is a document with headings.
+
+Flagging any of these is how a hygiene pass loses the author's trust for the findings that were real.

skilldrop_cli/data/packs/core/skills/output-hygiene/scripts/scrub.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""Deterministic surface-hygiene pass over agent-written text. Stdlib only, no network.
+
+    python3 scrub.py DRAFT.md                  # report findings, exit 1 if any
+    python3 scrub.py DRAFT.md --fix            # rewrite the file, report what changed
+    python3 scrub.py - < draft.md              # read stdin, report
+    python3 scrub.py - --fix < draft.md        # read stdin, write cleaned text to stdout
+    python3 scrub.py DRAFT.md --json           # machine-readable findings (for a hook)
+    python3 scrub.py MSG.txt --medium commit   # a medium where curly quotes ARE a defect
+    python3 scrub.py DRAFT.md --ascii --fix    # flatten curly quotes and dashes regardless
+
+Two tiers, and the split is the point:
+
+  AUTO   invisible characters, non-ASCII spacing, provenance trailers, chat closers.
+         Removing these cannot change what the text asserts, so --fix applies them.
+  REVIEW homoglyphs and typographic punctuation. A blind rewrite here corrupts meaning
+         (a Cyrillic 'а' may be intentional; an em dash in Markdown prose is correct),
+         so these are reported and left alone unless the caller opts in with --ascii.
+
+Typography is medium-dependent and the default medium is markdown, where curly quotes and
+em dashes are correct typesetting rather than defects — reporting them there would bury the
+findings that matter under one row per apostrophe. Pass --medium for a target that will
+re-encode the text (commit, code, csv, plaintext) and they become review findings.
+
+What this script cannot do is the other half of the job: prose tells — the cadence, the
+bolded lead-in on every bullet, the hedge vocabulary — need a model pass. See SKILL.md.
+
+Exit codes: 0 nothing left to fix · 1 findings remain · 2 usage or I/O error.
+"""
+import argparse
+import json
+import re
+import sys
+import unicodedata
+
+# --- AUTO tier ------------------------------------------------------------------------
+
+# Zero-width, directional, and formatting characters. They survive copy-paste, render as
+# nothing, and break grep, diff, and anything that compares strings.
+INVISIBLE = {
+    "​": "ZERO WIDTH SPACE",
+    "‌": "ZERO WIDTH NON-JOINER",
+    "‍": "ZERO WIDTH JOINER",
+    "⁠": "WORD JOINER",
+    "": "ZERO WIDTH NO-BREAK SPACE (BOM)",
+    "­": "SOFT HYPHEN",
+    "
": "LINE SEPARATOR",
+    "
": "PARAGRAPH SEPARATOR",
+    "‪": "LEFT-TO-RIGHT EMBEDDING",
+    "‫": "RIGHT-TO-LEFT EMBEDDING",
+    "‬": "POP DIRECTIONAL FORMATTING",
+    "‭": "LEFT-TO-RIGHT OVERRIDE",
+    "‮": "RIGHT-TO-LEFT OVERRIDE",
+    "⁦": "LEFT-TO-RIGHT ISOLATE",
+    "⁧": "RIGHT-TO-LEFT ISOLATE",
+    "⁨": "FIRST STRONG ISOLATE",
+    "⁩": "POP DIRECTIONAL ISOLATE",
+}
+
+# Spaces that are not U+0020. They look identical and silently break word-splitting,
+# Markdown table alignment, and YAML.
+SPACING = {
+    " ": "NO-BREAK SPACE",
+    " ": "NARROW NO-BREAK SPACE",
+    " ": "FIGURE SPACE",
+    " ": "THIN SPACE",
+    " ": "HAIR SPACE",
+    " ": "EN SPACE",
+    " ": "EM SPACE",
+    "　": "IDEOGRAPHIC SPACE",
+}
+
+# Whole-line provenance trailers added by an agent harness, not by the author.
+PROVENANCE = [
+    ("co-authored-by trailer", re.compile(r"^\s*co-authored-by:\s*claude\b.*$", re.I)),
+    ("generated-with footer", re.compile(r"^\s*(?:\S\s*)?generated with \[?claude code\]?.*$", re.I)),
+    ("generated-with footer", re.compile(r"^\s*(?:\S\s*)?generated (?:with|by) \[[^\]]+\]\(https://claude\.com[^)]*\).*$", re.I)),
+    # A signature is a dash, a name, and nothing else. A plain "-" opener is excluded and the
+    # tail is capped: "- Claude Code project settings: …" is a bullet, not a sign-off, and a
+    # cleaner that eats real list items loses the author's trust for the findings that were real.
+    ("assistant signature", re.compile(r"^\s*(?:—|–|--)\s*claude\b[\w.()\s-]{0,24}$", re.I)),
+]
+
+# A trailing paragraph that addresses the reader as a chat partner. Matched only as the
+# final block of the text, and only when it opens with one of these — a conservative list,
+# because a false positive here deletes real content.
+CLOSER_OPENERS = re.compile(
+    r"^(?:let me know (?:if|whether)|(?:i )?hope (?:this|that) helps|"
+    r"would you like me to|want me to|happy to (?:help|expand|adjust)|"
+    r"feel free to (?:ask|reach out|let me know)|"
+    r"if you(?:'| a)?d like(?:,| )?\s*i can)\b",
+    re.I,
+)
+
+# --- REVIEW tier ----------------------------------------------------------------------
+
+# Non-ASCII letters sitting inside an otherwise-ASCII word: the classic paste artifact
+# (and, occasionally, a deliberate spoof). Never auto-fixed — the correct ASCII letter is
+# a guess, and the word may be genuinely foreign.
+WORD = re.compile(r"[^\W\d_]+", re.UNICODE)
+
+TYPOGRAPHY = {
+    "‘": ("'", "LEFT SINGLE QUOTATION MARK"),
+    "’": ("'", "RIGHT SINGLE QUOTATION MARK"),
+    "“": ('"', "LEFT DOUBLE QUOTATION MARK"),
+    "”": ('"', "RIGHT DOUBLE QUOTATION MARK"),
+    "–": ("-", "EN DASH"),
+    "—": ("--", "EM DASH"),
+    "…": ("...", "HORIZONTAL ELLIPSIS"),
+    "′": ("'", "PRIME"),
+    "″": ('"', "DOUBLE PRIME"),
+}
+
+
+def _positions(text):
+    """Offset -> (line, col), both 1-based. Computed once; the scan is O(n)."""
+    line, col, out = 1, 1, []
+    for ch in text:
+        out.append((line, col))
+        if ch == "\n":
+            line, col = line + 1, 1
+        else:
+            col += 1
+    return out
+
+
+def _finding(cls, tier, line, col, detail, excerpt):
+    return {"class": cls, "tier": tier, "line": line, "col": col,
+            "detail": detail, "excerpt": excerpt}
+
+
+def _excerpt(text, offset, width=36):
+    lo = text.rfind("\n", 0, offset) + 1
+    hi = text.find("\n", offset)
+    hi = len(text) if hi == -1 else hi
+    frag = text[lo:hi]
+    rel = offset - lo
+    start = max(0, rel - width // 2)
+    snippet = frag[start:start + width].replace("\t", " ")
+    return ("…" if start > 0 else "") + snippet.strip() + ("…" if start + width < len(frag) else "")
+
+
+# Media where typographic punctuation survives and is correct. Everywhere else it is a
+# defect waiting for a re-encode.
+TYPOGRAPHY_OK = {"markdown", "html"}
+
+
+def scan(text, ascii_mode=False, medium="markdown"):
+    """Return (findings, cleaned_text). cleaned_text applies the AUTO tier, plus the
+    REVIEW typography tier when ascii_mode is on. Findings describe the ORIGINAL text."""
+    findings = []
+    report_typography = ascii_mode or medium not in TYPOGRAPHY_OK
+    pos = _positions(text)
+
+    # --- character-level classes
+    for i, ch in enumerate(text):
+        line, col = pos[i]
+        if ch in INVISIBLE:
+            findings.append(_finding("invisible", "auto", line, col,
+                                     f"U+{ord(ch):04X} {INVISIBLE[ch]} — renders as nothing",
+                                     _excerpt(text, i)))
+        elif ch in SPACING:
+            findings.append(_finding("spacing", "auto", line, col,
+                                     f"U+{ord(ch):04X} {SPACING[ch]} — not a plain space",
+                                     _excerpt(text, i)))
+        elif ch in TYPOGRAPHY and report_typography:
+            repl, name = TYPOGRAPHY[ch]
+            findings.append(_finding("typography", "auto" if ascii_mode else "review", line, col,
+                                     f"U+{ord(ch):04X} {name} — flatten to {repl!r} for plain-text targets",
+                                     _excerpt(text, i)))
+
+    # --- homoglyphs: a non-ASCII letter inside a word that is otherwise ASCII
+    for m in WORD.finditer(text):
+        word = m.group(0)
+        # A homoglyph is a LETTER that impersonates another letter. Superscripts and symbols
+        # inside a word — the ² in "O(n²)" — are typography, and flagging them is the noise
+        # that teaches an author to ignore the findings that were real.
+        odd = [(k, c) for k, c in enumerate(word)
+               if ord(c) > 127 and unicodedata.category(c).startswith("L")]
+        if not odd or len(odd) == len(word):
+            continue
+        for k, c in odd:
+            off = m.start() + k
+            line, col = pos[off]
+            try:
+                name = unicodedata.name(c)
+            except ValueError:
+                name = "UNNAMED"
+            findings.append(_finding("homoglyph", "review", line, col,
+                                     f"U+{ord(c):04X} {name} inside ASCII word {word!r} — verify before replacing",
+                                     _excerpt(text, off)))
+
+    # --- line-level provenance
+    drop_lines = set()
+    for n, raw in enumerate(text.split("\n"), start=1):
+        for label, pattern in PROVENANCE:
+            if pattern.match(raw):
+                findings.append(_finding("provenance", "auto", n, 1,
+                                         f"{label} — harness-added, not authored", raw.strip()))
+                drop_lines.add(n)
+                break
+
+    cleaned = "\n".join(l for n, l in enumerate(text.split("\n"), start=1) if n not in drop_lines)
+    if drop_lines:
+        cleaned = re.sub(r"\n{3,}", "\n\n", cleaned)
+        cleaned = re.sub(r"\n+\Z", "\n" if text.endswith("\n") else "", cleaned)
+
+    # --- trailing chat closer, measured against the text as it stands after line drops
+    trimmed = cleaned.rstrip()
+    blocks = re.split(r"\n\s*\n", trimmed)
+    if len(blocks) > 1 and CLOSER_OPENERS.match(blocks[-1].strip()):
+        tail = blocks[-1]
+        idx = trimmed.rfind(tail)
+        findings.append(_finding("closer", "auto", trimmed.count("\n", 0, max(idx, 0)) + 1, 1,
+                                 "trailing chat closer — addresses a chat partner, not a reader",
+                                 " ".join(tail.split())[:80]))
+        cleaned = "\n\n".join(blocks[:-1]).rstrip() + ("\n" if text.endswith("\n") else "")
+
+    # --- character substitutions
+    for ch in INVISIBLE:
+        cleaned = cleaned.replace(ch, "\n" if ch in ("
", "
") else "")
+    for ch in SPACING:
+        cleaned = cleaned.replace(ch, " ")
+    if ascii_mode:
+        for ch, (repl, _) in TYPOGRAPHY.items():
+            cleaned = cleaned.replace(ch, repl)
+
+    findings.sort(key=lambda f: (f["line"], f["col"]))
+    return findings, cleaned
+
+
+TIER_ORDER = {"auto": 0, "review": 1}
+
+
+def report(path, findings, fixed, ascii_mode, medium):
+    auto = [f for f in findings if f["tier"] == "auto"]
+    review = [f for f in findings if f["tier"] == "review"]
+    head = (f"{path} [{medium}]: {len(findings)} finding(s) — "
+            f"{len(auto)} auto, {len(review)} review")
+    lines = [head, "=" * len(head)]
+    for tier, group, note in (
+        ("auto", auto, "applied" if fixed else "safe to apply with --fix"),
+        ("review", review, "left alone — judgment required" + ("" if ascii_mode else "; --ascii flattens typography")),
+    ):
+        if not group:
+            continue
+        lines.append(f"\n[{tier}] {len(group)} — {note}")
+        for f in group:
+            lines.append(f"  {str(f['line']) + ':' + str(f['col']):<9} {f['class']:<11} {f['detail']}")
+            lines.append(f"  {'':<9} {'':<11} {f['excerpt']}")
+    if not findings:
+        lines = [f"{path} [{medium}]: clean"]
+    return "\n".join(lines)
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Report and optionally remove machine artifacts from agent-written text.")
+    ap.add_argument("paths", nargs="+", help="files to scan, or - for stdin")
+    ap.add_argument("--fix", action="store_true",
+                    help="apply the auto tier (rewrites files in place; stdin goes to stdout)")
+    ap.add_argument("--medium", default="markdown",
+                    choices=["markdown", "html", "plaintext", "commit", "code", "csv"],
+                    help="where the text is going; decides whether typographic punctuation "
+                         "is a defect (default: markdown, where it is not)")
+    ap.add_argument("--ascii", action="store_true",
+                    help="report AND flatten curly quotes, dashes, and ellipses whatever the medium")
+    ap.add_argument("--json", action="store_true", help="emit findings as JSON")
+    ap.add_argument("--quiet", action="store_true", help="exit code only, no report")
+    args = ap.parse_args()
+
+    if args.json and args.quiet:
+        ap.error("--json and --quiet are mutually exclusive")
+
+    results, remaining = [], 0
+    for path in args.paths:
+        try:
+            text = sys.stdin.read() if path == "-" else open(path, encoding="utf-8").read()
+        except OSError as e:
+            print(f"scrub.py: cannot read {path}: {e}", file=sys.stderr)
+            return 2
+        except UnicodeDecodeError:
+            print(f"scrub.py: {path} is not UTF-8 text", file=sys.stderr)
+            return 2
+
+        findings, cleaned = scan(text, ascii_mode=args.ascii, medium=args.medium)
+        if args.fix and cleaned != text:
+            if path == "-":
+                sys.stdout.write(cleaned)
+            else:
+                try:
+                    with open(path, "w", encoding="utf-8") as f:
+                        f.write(cleaned)
+                except OSError as e:
+                    print(f"scrub.py: cannot write {path}: {e}", file=sys.stderr)
+                    return 2
+        elif args.fix and path == "-":
+            sys.stdout.write(cleaned)
+
+        left = [f for f in findings if f["tier"] == "review" or not args.fix]
+        remaining += len(left)
+        results.append({"path": path, "findings": findings,
+                        "fixed": args.fix and cleaned != text})
+
+    if args.json:
+        print(json.dumps({"results": results, "remaining": remaining}, indent=2))
+    elif not args.quiet:
+        out = sys.stderr if (args.fix and "-" in args.paths) else sys.stdout
+        for r in results:
+            print(report(r["path"], r["findings"], r["fixed"], args.ascii, args.medium), file=out)
+    return 1 if remaining else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())