skilldrop-cli 0.11.3 → 0.11.5

package/README.md

@@ -3,9 +3,9 @@
 [![npm](https://img.shields.io/npm/v/skilldrop-cli)](https://www.npmjs.com/package/skilldrop-cli)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 56 skills, filterable by pack, tag, and model tier.
+**[Browse the catalogue →](https://sananthanarayan.github.io/skilldrop/)** — all 57 skills, filterable by outcome, pack, tag, and model tier.
 
-**56 portable AI-agent skills for the deliverables knowledge workers actually ship** — diagrams, design docs, ADRs, PRDs, runbooks, decks, decision logs, threat models, adversarial reviews — installable into **Claude Code**, **Cursor**, **Kiro**, **Codex**, **GitHub Copilot**, and any AI tool that accepts custom instructions, one skill or one role-based pack at a time:
+**57 portable AI-agent skills for the deliverables knowledge workers actually ship** — diagrams, design docs, ADRs, PRDs, runbooks, decks, decision logs, threat models, adversarial reviews — installable into **Claude Code**, **Cursor**, **Kiro**, **Codex**, **GitHub Copilot**, and any AI tool that accepts custom instructions, one skill or one role-based pack at a time:
 
 ```bash
 npx skilldrop-cli install --pack product-manager     # or: solution-architect, dev-team,
@@ -77,6 +77,7 @@ flowchart LR
 |---|---|
 | [`brief-intake`](skills/brief-intake/SKILL.md) | Upstream collector. Takes raw mess — a Slack thread, meeting transcript, ticket, email chain, paragraph of notes — and emits a structured brief shaped for whichever downstream skill comes next (ADR, design doc, runbook, exec summary, deck, comparison matrix, decision log). Every field is tagged `[explicit] / [implied] / [inferred] / [missing]` with verbatim quotes from the source. |
 | [`doc-critique`](skills/doc-critique/SKILL.md) | Counterpart reviewer. Takes an existing doc (ADR, design doc, runbook, exec summary, comparison matrix, deck, decision log) and produces a structured critique against the same rubrics the generators enforce — verdict + severity-tagged findings (blocker / major / minor / nit) with quoted evidence and concrete fixes, plus a "what's working" section. |
+| [`output-hygiene`](skills/output-hygiene/SKILL.md) | Pre-ship surface pass. Runs a stdlib-only script over agent-written text to find what the machine put there — invisible Unicode, non-breaking spaces, homoglyphs, harness-added provenance trailers, trailing chat closers — reporting each with its codepoint and line, then sweeps the prose for the tells a script cannot see and quotes every one with a rewrite. Separates what is safe to auto-apply from what needs a decision, and holds the provenance class where an academic, employer, or contribution policy requires disclosure. |
 
 ### Planning & delivery
 
@@ -235,12 +236,12 @@ Categories (above) say what a skill *is*; packs say *who needs it*. [`packs.json
 
 | Pack | Skills | For |
 |---|---|---|
-| `solution-architect` | 15 | Design-phase artifacts: diagrams, ADRs, design docs, contracts, schemas, threat models, and the reviews that gate them |
-| `product-manager` | 12 | Direction to requirements: PR/FAQs, strategy frameworks, OKRs, PRDs, journey maps, story splitting, success measurement |
-| `dev-team` | 11 | Build-and-ship loop: implementation with adversarial review, test plans, triage, migrations, release notes, quality gates |
-| `stakeholder-comms` | 8 | Non-technical audiences: audience profiling, deck outlines and real `.pptx` decks, exec summaries, decision logs, guides |
+| `solution-architect` | 17 | Design-phase artifacts: diagrams, ADRs, design docs, contracts, schemas, threat models, and the reviews that gate them |
+| `dev-team` | 14 | Build-and-ship loop: implementation with adversarial review, test plans, triage, migrations, release notes, quality gates, pre-ship hygiene |
+| `product-manager` | 13 | Direction to requirements: PR/FAQs, strategy frameworks, OKRs, PRDs, journey maps, story splitting, success measurement |
+| `ai-engineering` | 12 | Build and run AI systems: agent loop design, subagent orchestration, spend budgets, eval harnesses, usage reporting, data contracts |
+| `stakeholder-comms` | 9 | Non-technical audiences: audience profiling, deck outlines and real `.pptx` decks, exec summaries, decision logs, guides |
 | `sre-oncall` | 5 | Operate the service: runbooks, observability design, incident comms, postmortems, capacity/cost models |
-| `ai-engineering` | 6 | Build and run AI systems: agent loop design, subagent orchestration, spend budgets, eval harnesses, usage reporting, data contracts |
 
 ```bash
 python3 pack.py                                  # list packs
@@ -252,6 +253,26 @@ python3 pack.py product-manager --install --dest .cursor/skills   # any dir, for
 
 For non-Claude IDEs, `--dest` drops the folders where your tool expects them; the per-IDE wiring steps below still apply. Packs are metadata only — skills stay in flat `skills/<name>` folders, so per-skill `cp -R` installs keep working unchanged ([RFC-0001](docs/rfcs/0001-skill-packs.md) records the design decision).
 
+## Outcomes — browse by why you're here
+
+Packs answer *who am I*. Outcomes answer *why did I open this*. The seven below are the nine
+categories above, restated as the things people actually arrive wanting to do, and they live in
+the `outcomes` block of [`packs.json`](packs.json) so the [catalogue site](https://sananthanarayan.github.io/skilldrop/)
+can filter on them. Every skill belongs to at least one; `validate.py` enforces it.
+
+| Outcome | Skills | What it covers |
+|---|---|---|
+| `design-the-system` | 15 | Decision records, design docs, diagrams, contracts, schemas, migration and threat models, agentic design |
+| `decide-what-to-build` | 11 | Press releases, strategy frameworks, OKRs, business cases, requirements, PRDs, success metrics |
+| `build-and-review-software` | 11 | Supervised implementation, review panels, test plans, triage, accessibility and static-analysis passes |
+| `explain-it-to-decision-makers` | 6 | Audience profiling, deck outlines and real decks, exec summaries, decision logs, guides |
+| `govern-ai-use` | 6 | Readiness, use-case triage, rollout, acceptable-use policy, adoption staging, usage reporting |
+| `run-and-recover-the-service` | 5 | Runbooks, observability design, release notes, incident comms, postmortems |
+| `get-a-draft-ready-to-ship` | 3 | Collect a messy input, critique the argument, strip the machine artifacts |
+
+Outcomes are a browse aid, not an install unit — there is no `--outcome` flag. Install by skill
+or by pack.
+
 ## Installing a skill into your IDE
 
 ### Quickest: the skilldrop CLI
@@ -276,14 +297,29 @@ npx skilldrop-cli list --json                            # machine-readable: lis
 
 ### Or: the Claude Code plugin marketplace
 
-skilldrop is also a **Claude Code plugin marketplace** — install the whole catalogue as one plugin, no npm step:
+skilldrop is also a **Claude Code plugin marketplace** — one marketplace, seven plugins, no npm step. Add it once:
 
 ```text
 /plugin marketplace add sananthanarayan/skilldrop
-/plugin install skilldrop@skilldrop
 ```
 
-Every skill then invokes as `/skilldrop:<name>` (e.g. `/skilldrop:prfaq`), and the reviewer subagents come with it. The marketplace ships the flat `skills/` and `agents/` trees at the repo root unchanged — same copy-install premise, expressed in Claude's own plugin format. `.claude-plugin/{marketplace,plugin}.json` are generated from `package.json` by [`build_marketplace.py`](build_marketplace.py) (`--check` guards drift in CI). Use the CLI above when you want per-pack or per-skill granularity, another IDE, or hooks; use the marketplace when you're in Claude Code and want everything in two lines. Rationale and the deferred per-pack-plugin step: [RFC-0014](docs/rfcs/0014-agentbundle-interop.md).
+Then take the whole catalogue, or just your role's pack:
+
+```text
+/plugin install skilldrop@skilldrop             # all 57 skills + 3 reviewer subagents
+/plugin install solution-architect@skilldrop    # 17 skills
+/plugin install dev-team@skilldrop              # 14 skills + the 3 reviewer subagents
+/plugin install product-manager@skilldrop       # 13 skills
+/plugin install ai-engineering@skilldrop        # 12 skills
+/plugin install stakeholder-comms@skilldrop     # 9 skills
+/plugin install sre-oncall@skilldrop            # 5 skills
+```
+
+Every skill then invokes as `/<plugin>:<name>` (e.g. `/skilldrop:prfaq`). The whole-catalogue plugin ships the flat `skills/` and `agents/` trees at the repo root unchanged — same copy-install premise, expressed in Claude's own plugin format.
+
+The six **pack plugins** work differently, because a plugin's skills have to sit in a `skills/` folder inside the plugin. Rather than duplicate every skill into six directories on `main` — physical packs, which [RFC-0001](docs/rfcs/0001-skill-packs.md) rejected — the marketplace entries use Claude's `git-subdir` source to point at `packs/<name>/` on a generated [`plugins`](https://github.com/sananthanarayan/skilldrop/tree/plugins) branch, rebuilt by CI on every push to main. Nothing moves in the source tree, and you still only ever type the one `marketplace add`. A pack carries the reviewer subagents its own skills delegate to, so `dev-team` brings the review panel and `sre-oncall` does not.
+
+`.claude-plugin/{marketplace,plugin}.json` are generated from `package.json` + `packs.json` by [`build_marketplace.py`](build_marketplace.py) (`--check` guards drift in CI; `--dist` renders the branch). Use the CLI above when you want per-skill granularity, another IDE, or hooks; use the marketplace when you're in Claude Code. Rationale: [RFC-0027](docs/rfcs/0027-retire-agentbundle-export.md).
 
 ### Hooks (opt-in) — wire a skill to an event
 
@@ -336,7 +372,7 @@ npx skilldrop-cli install --pack starter --from ../local-catalog
 npx skilldrop-cli update      # updates bundled and third-party skills side by side — the ledger remembers each skill's source
 ```
 
-The CLI also reads **agentbundle-shaped catalogs** ([agent-ready-repo](https://github.com/eugenelim/agent-ready-repo)) — `packs/<pack>/.apm/skills/<name>/SKILL.md` with a `pack.toml` per pack — so you can install *its* packs through the same command ([RFC-0014](docs/rfcs/0014-agentbundle-interop.md)). Both shapes share the agentskills.io `SKILL.md`, so the reader just maps his packs onto the accessors above:
+The CLI also reads **agentbundle-shaped catalogs** ([agent-ready-repo](https://github.com/eugenelim/agent-ready-repo)) — `packs/<pack>/.apm/skills/<name>/SKILL.md` with a `pack.toml` per pack — so you can install *its* packs through the same command ([RFC-0014](docs/rfcs/0014-agentbundle-interop.md)). This is one-directional by design: skilldrop reads his shape, and no longer publishes a generated catalogue back into it ([RFC-0027](docs/rfcs/0027-retire-agentbundle-export.md)). Both shapes share the agentskills.io `SKILL.md`, so the reader just maps his packs onto the accessors above:
 
 ```bash
 npx skilldrop-cli packs --from https://github.com/eugenelim/agent-ready-repo
@@ -527,8 +563,9 @@ Full contributor guide — the three lanes, the PR gates, and the release flow
 4. If your skill needs scripts, drop them in `scripts/` and reference them with a path relative to the skill folder — **avoid hard-coding `${CLAUDE_SKILL_DIR}` only**; show both paths so non–Claude-Code users aren't stuck.
 5. Add an `evals/` folder: `evals.json` (at least one realistic prompt with a list of assertions the output must satisfy) and `eval_queries.json` (phrases that should and should **not** trigger the skill). These double as the checklist for the manual test pass and keep the `description` honest about when the skill fires.
 6. Add an entry to the **Skills in this repo** table above and to the **Installing dependencies** table.
-7. Add the skill to at least one pack in `packs.json`.
-8. Run `python3 validate.py` from the repo root — it checks name consistency, the tier sync with `model-routing.json`, the `related`↔SKILL.md reference sync, description sync, pack membership, and eval file shape.
+7. Add the skill to at least one pack **and** at least one outcome in `packs.json`.
+8. If the change is going out in a release, add a bullet to [`CHANGELOG.md`](CHANGELOG.md) under the new version — the site build fails without one.
+9. Run `python3 validate.py` from the repo root — it checks name consistency, the tier sync with `model-routing.json`, the `related`↔SKILL.md reference sync, description sync, pack and outcome membership, and eval file shape.
 
 ## License
 

package/bin/skilldrop.js

@@ -204,6 +204,16 @@ function skillDir(cat, s) {
   if (cat.shape === "apm") return cat.skillIndex[s] && cat.skillIndex[s].dir;
   return path.join(cat.skillsDir, s);
 }
+// Skill names reach RegExp when unwiring hooks. skillExists() proves a directory exists; it
+// does not prove the name is regex-safe, and a third-party catalog (RFC-0003) may name a
+// skill anything a filesystem accepts. Escape before interpolating.
+// Read a file if it is there. Checking existsSync first then reading is a race: the file can
+// vanish in between and the read throws. Handle the absence, do not predict it.
+function readIfPresent(p, absent = "") {
+  try { return fs.readFileSync(p, "utf8"); }
+  catch (e) { if (e.code === "ENOENT") return absent; throw e; }
+}
+function reEscape(s) { return String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }
 function skillExists(cat, s) { const d = skillDir(cat, s); return !!d && fs.existsSync(d); }
 function manifestOf(cat, s) {
   if (cat.shape === "apm") {
@@ -591,7 +601,7 @@ function gitRoot(startDir) {
 function writeGitPreCommitHook(root, skill, hook) {
   const p = path.join(root, ".git", "hooks", "pre-commit");
   const marker = `skilldrop-hook:${skill}:pre-commit-review`;
-  let body = fs.existsSync(p) ? fs.readFileSync(p, "utf8") : "";
+  let body = readIfPresent(p);  // read-and-handle, not check-then-read
   if (!body.startsWith("#!")) body = "#!/bin/sh\n" + body;
   if (body.includes(marker)) return p; // already wired
   const line = `echo "skilldrop: run /${hook.action} on your staged changes before committing — ${hook.description}"`;
@@ -606,8 +616,9 @@ function writeGitPreCommitHook(root, skill, hook) {
 // or null if the file exists but is malformed (we never clobber unparseable JSON).
 function writeClaudeSessionHook(settingsPath, skill, hook) {
   let data = {};
-  if (fs.existsSync(settingsPath)) {
-    try { data = JSON.parse(fs.readFileSync(settingsPath, "utf8")); }
+  const raw = readIfPresent(settingsPath, null);
+  if (raw !== null) {
+    try { data = JSON.parse(raw); }
     catch (e) { return null; }
   }
   data.hooks = data.hooks || {};
@@ -653,18 +664,20 @@ function removeHooksFor(skill, dest, ide) {
   const root = gitRoot(process.cwd());
   if (root) {
     const p = path.join(root, ".git", "hooks", "pre-commit");
-    if (fs.existsSync(p)) {
-      const body = fs.readFileSync(p, "utf8");
-      const re = new RegExp(`\\n?# >>> skilldrop-hook:${skill}:[^\\n]* >>>[\\s\\S]*?# <<< skilldrop-hook:${skill}:[^\\n]* <<<\\n?`, "g");
+    const body = readIfPresent(p, null);
+    if (body !== null) {
+      const q = reEscape(skill);
+      const re = new RegExp(`\\n?# >>> skilldrop-hook:${q}:[^\\n]* >>>[\\s\\S]*?# <<< skilldrop-hook:${q}:[^\\n]* <<<\\n?`, "g");
       const next = body.replace(re, "\n");
       if (next !== body) fs.writeFileSync(p, next);
     }
   }
   if (ide === "claude") {
     const sp = path.join(path.dirname(dest), "settings.json");
-    if (fs.existsSync(sp)) {
+    const raw = readIfPresent(sp, null);
+    if (raw !== null) {
       try {
-        const data = JSON.parse(fs.readFileSync(sp, "utf8"));
+        const data = JSON.parse(raw);
         const arr = data.hooks && data.hooks.SessionStart;
         if (Array.isArray(arr)) {
           const kept = arr.filter((e) => !JSON.stringify(e).includes(`skilldrop-hook:${skill}:`));

package/model-routing.json

@@ -142,6 +142,7 @@
     "observability-plan": { "tier": "standard", "rationale": "Methodology synthesis against fixed SRE practices (golden signals, burn-rate alerting, pillar split). SLO calibration needs judgment but is bounded; escalate via ambiguous-input on contested reliability targets." },
     "council-review": { "tier": "heavy", "rationale": "Multi-perspective deliberation + weighted reconciliation across distinct expert seats. Cheaper models collapse the seats into one voice and either manufacture or miss the real cruxes. Never downgrade." },
     "devils-advocate": { "tier": "heavy", "rationale": "Adversarial code review across four lenses. Cheaper models miss edge cases and under-call severity — the whole value is the hard thinking. Never downgrade." },
+    "output-hygiene": { "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." },
     "doc-critique": { "tier": "heavy", "rationale": "Adversarial doc review against rubrics. Same as devils-advocate: the value is catching what a fast pass misses. Never downgrade." },
     "tech-comparison-matrix": { "tier": "heavy", "rationale": "Weighted multi-criteria judgment with a recommendation. Mis-weighting is the failure mode; heavy is worth it. Never downgrade." },
     "threat-model": { "tier": "heavy", "rationale": "Adversarial reasoning over a design — cheaper models emit checklist residue, miss authz/insider paths, and inflate severity. Never downgrade." },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "description": "Portable AI-agent skills for the deliverables knowledge workers ship — diagrams, ADRs, PRDs, runbooks, decks, reviews — installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Virtual skill packs — role-based bundles for one-command install. Packs are METADATA ONLY: skills stay in flat skills/<name> folders (golden rule: skills are discovered by path), a skill may belong to several packs, and every skill must belong to at least one (validate.py enforces both directions). Install a pack with `python3 pack.py <pack> --install`; see README. Rationale: docs/rfcs/0001-skill-packs.md.",
+  "$comment": "Virtual skill packs — role-based bundles for one-command install. Packs are METADATA ONLY: skills stay in flat skills/<name> folders (golden rule: skills are discovered by path), a skill may belong to several packs, and every skill must belong to at least one (validate.py enforces both directions). Install a pack with `python3 pack.py <pack> --install`; see README. Rationale: docs/rfcs/0001-skill-packs.md. `outcomes` (RFC-0026) is the second browse axis: packs say WHO needs a skill, outcomes say WHY someone opens the catalogue. It is the README's nine categories restated as seven outcomes and made machine-readable so the site cannot drift from them. Outcomes are a browse aid only — not an install unit — and validate.py enforces the same two-way check packs get.",
   "version": "0.1.0",
   "packs": {
     "solution-architect": {
@@ -57,7 +57,8 @@
         "release-notes",
         "sonar-onboard",
         "sonar-review",
-        "accessibility-audit"
+        "accessibility-audit",
+        "output-hygiene"
       ]
     },
     "sre-oncall": {
@@ -80,7 +81,8 @@
         "exec-summary",
         "decision-log",
         "guide-builder",
-        "doc-critique"
+        "doc-critique",
+        "output-hygiene"
       ]
     },
     "ai-engineering": {
@@ -100,5 +102,99 @@
         "agent-adoption-stage"
       ]
     }
+  },
+  "outcomes": {
+    "decide-what-to-build": {
+      "description": "Turn a direction into a committed, measurable plan: press releases, strategy frameworks, OKRs, business cases, requirements, PRDs, and the metrics that will say whether it worked.",
+      "skills": [
+        "prfaq",
+        "strategy-analysis",
+        "okr-cascade",
+        "business-case",
+        "capacity-cost-model",
+        "requirements-interview",
+        "prd-draft",
+        "nfr-spec",
+        "success-metrics",
+        "user-story-splitter",
+        "user-journey-map"
+      ]
+    },
+    "design-the-system": {
+      "description": "Commit the shape before the code: decision records, design docs, diagrams, contracts, schemas, migration and threat models, and the design of any agentic parts.",
+      "skills": [
+        "adr-generator",
+        "design-doc",
+        "architecture-diagrams",
+        "reverse-architecture",
+        "figma-diagrams",
+        "api-contract-draft",
+        "db-schema-design",
+        "data-contract",
+        "tech-comparison-matrix",
+        "threat-model",
+        "agent-threat-model",
+        "migration-plan",
+        "agent-loop-design",
+        "subagent-design",
+        "agent-budget"
+      ]
+    },
+    "build-and-review-software": {
+      "description": "The loop around the code itself: supervised implementation, adversarial review panels, test plans, triage, accessibility and static-analysis passes, and the policy files agents read.",
+      "skills": [
+        "feature-implement-loop",
+        "pre-merge-review",
+        "devils-advocate",
+        "council-review",
+        "accessibility-audit",
+        "sonar-onboard",
+        "sonar-review",
+        "test-plan-generator",
+        "bug-triage",
+        "agents-md-generator",
+        "llm-eval-harness"
+      ]
+    },
+    "run-and-recover-the-service": {
+      "description": "Operate what shipped: runbooks, observability design, release notes, incident communication, and the postmortem that closes the loop.",
+      "skills": [
+        "runbook-generator",
+        "observability-plan",
+        "release-notes",
+        "incident-comms",
+        "postmortem-generator"
+      ]
+    },
+    "explain-it-to-decision-makers": {
+      "description": "Get a non-technical audience to a decision: audience profiling, deck outlines and real decks, exec summaries, decision logs, and how-to guides.",
+      "skills": [
+        "audience-profile",
+        "slide-outliner",
+        "deck-builder",
+        "exec-summary",
+        "decision-log",
+        "guide-builder"
+      ]
+    },
+    "govern-ai-use": {
+      "description": "Adopt AI deliberately and prove what it is doing: readiness assessment, use-case triage, rollout plans, acceptable-use policy, adoption staging, and usage reporting.",
+      "skills": [
+        "ai-readiness-assessment",
+        "ai-use-case-triage",
+        "ai-adoption-rollout",
+        "ai-usage-policy",
+        "agent-adoption-stage",
+        "ai-usage-report"
+      ]
+    },
+    "get-a-draft-ready-to-ship": {
+      "description": "The passes either side of a generator: collect a messy input into a structured brief, critique the argument, and strip the machine artifacts before it leaves the building.",
+      "skills": [
+        "brief-intake",
+        "doc-critique",
+        "output-hygiene"
+      ]
+    }
   }
 }

package/skills/output-hygiene/SKILL.md

@@ -0,0 +1,95 @@
+---
+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.

package/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 }
+]

package/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"
+      ]
+    }
+  ]
+}

package/skills/output-hygiene/manifest.json

@@ -0,0 +1,30 @@
+{
+  "name": "output-hygiene",
+  "version": "0.1.0",
+  "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"
+  ],
+  "tags": [
+    "hygiene",
+    "cleanup",
+    "unicode",
+    "provenance",
+    "ai-detection",
+    "pre-ship"
+  ],
+  "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."
+  }
+}

package/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.

package/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())