@tduyng/pi-timbre 0.0.2 → 0.0.4

package/README.md

@@ -1,152 +1,117 @@
-# @tduyng/pi-timbre
-
-Constrains the agent's prose and code before tokens are generated, then measures what still gets through.
-
-For full design rationale, see `src/README.md`.
-
-## What it adds
-
-`before_agent_start`: injects a constraint block into the system prompt each turn, which is the `Never` and `Code` sections of the catalog and nothing else; the five judgment sections are served on demand by `timbre_review_guide`.
-
-`tool_call`: records the path a write touched, for the once-per-turn code check below, and notices a prose write once per file per session. It refuses nothing.
-
-    There was a preflight here that blocked the write, and this paragraph used to say so. It was removed in `0df54db3` because it repeated the report the result already carried, after `7f69c7ab` had already replaced the refusal with a note for the same reason. A blocked write discards the tool call and costs a full regeneration, which is more than the tell it prevented is worth.
-
-The write is never refused, because refusing it discards the tool call and costs a full regeneration. One note per file per session: the model edits the spans the note names, and that edit is another write, which is another read.
-
-`tool_result` note: appends a tell report to write and edit results for prose and TypeScript files.
-
-    ### What the score was worth on `english`, and why the note is gone
-
-    It was a label, not a discriminator, on the checkpoint serving, and no reformulation of it fixed that. Seventeen samples, nine written by people and eight of this model's own replies: pi's vendor documentation, this repository's `AGENTS.md`, `GUIDE.md` from its first commit, and assistant replies from real sessions. All seventeen came back level 2. It is not reading length, since 200 characters of `AGENTS.md` scores the same as 3,500, and the argmax is not hiding a usable threshold either: the probability of level 0 separates the two classes at 0.167 AUC and `1 - p(level 2)` at 0.250, where chance is 0.5.
-
-    Three question shapes were measured on those same seventeen samples. The one as shipped scored 0.264. Rewriting the criteria so each level describes what it means, rather than naming it, scored 0.250. Replacing the three-level score with a single continuous judgement scored 0.514. None separates, so this is the checkpoint's ceiling and not the wording. `PLAN.md` records the same wall from the other side: making an instruction more precise collapsed its spread from 0.380 to 0.199, and the vaguer phrasing carried more signal than the precise one.
-
-    The one place a session does record who wrote a paragraph is the transcript itself: a user message is human and an assistant message is machine. Over eighty real passages from this repository's sessions, forty of each, the score reaches 0.512 AUC, at means 0.706 against 0.764 with the wrong one on top, and the note would have fired on 30 of the 40 machine passages and 26 of the 40 human ones. Scored on markdown files instead, thirteen same-file pairs where the agent had rewritten an earlier version, it reaches 0.500, though both sides of those pairs are agent-written and the test cannot settle much. The note was three quarters true and three quarters false at the same time, which is the worst of both: it spends 110ms of server time per prose write to tell the model to rewrite prose that a person wrote.
-
-    So the label is gone, and with it the switch, the shadow records, the turn-end drain and the write-path call. `PLAN.md`'s own rule gives the reason: a question earns a call only when the decision it reads exists in the transcript, and the note was reading a question the transcript does not answer.
-
-`message_end`: silently records tell density per assistant reply.
-
-`timbre_review_guide` tool: serves the judgment procedure on request.
-
-`/timbre` subcommands: `on`, `off`, `fix <paths>`, `reset`, `status`, `stats`.
-
-`ctrl+alt+t` shortcut: toggles prevention with the same persistence as the command. The status bar shows `on` or `off`.
-
-## Token costs
+<!-- lint-disable -- this file names the tells it documents -->
 
-The constraint block sits in the system prompt every turn. Pi marks it cacheable, and Anthropic bills cache writes at 1.25x and reads at 0.1x:
-
-- The catalog, 986 tokens, and it is the only standing cost this package has
-- Per turn, cache warm: 99 tokens
-- Per turn, cache cold: 1,085 tokens
-
-The constraint block is the only part of the rules the model reads before it writes, so it is built whenever prevention is on, . The read judges what landed and fails open, and a rule the model only meets afterwards is a rule it already broke.
-
-Code is checked once per turn, not once per write. An oxlint spawn is about 130ms of fixed cost and a file adds 2-3ms, so a per-write check paid that fixed cost again for every file and still made the write wait for it. Batched at the end of the turn it is one spawn for everything the turn touched, off the write's path. It runs wherever the session runs, so there is no per-project command to remember.
-
-Two arrangements came before this one and both failed. Sent as a follow-up, the note cost a whole model request, and by the time the model read one it had usually finished: sessions show it replying that the reports were stale and described states it had already replaced and committed. Fixing a finding also changes the file's signature, which earned a second follow-up for the tell the fix uncovered, so one file could produce a stream of them. Moved onto the next write or edit result, the note was unambiguous but dropped whenever a turn's last act was the write itself.
-
-The note goes into the session as an entry at the turn's end. It used to ride the next write or edit result, which was unambiguous but dropped the note whenever a turn's last act was the write itself; a live check wrote `export function go(): unknown`, the scan found it, and the model never heard about it. An entry costs no model request, keeps its own provenance instead of borrowing a command's output, and is always delivered. Nothing else stands in for it, because nothing blocks a write. What remains is the deterministic tell report on the write and edit result, which covers the mechanical tells in the text the model wrote, so what is given up is the code check's end-of-task report rather than the prose report.
-
-A 30-turn session costs about 3k tokens with a 1-hour cache TTL. The same session costs 33k if every turn goes cold, which is what Pi's default 5-minute TTL produces.
+# @tduyng/pi-timbre
 
-## What prevention is worth
+Keeps Markdown and TypeScript inside a project's rules before the writing happens, instead of cleaning it up afterwards.
 
-Two runs, same model, scratch projects, prevention seeded through the extension's own persisted setting, replies scored by the deterministic scan. Counts are raw rather than per 1,000 characters: in the three-arm run the arms wrote within 7 percent of each other per reply, so normalising by length only re-expressed the same ordering.
+Rules go into the system prompt before the model answers. Markdown is scanned when a file is written. TypeScript is checked against `dmmulroy/anti-slop` once per turn. Nothing is rewritten after generation.
 
-Mechanical tells are the em dashes, semicolons and invisible characters. Judgment tells are the wall paragraphs and the monotone cadence.
+## Before the first token
 
-| run | arm                       | replies | mechanical | judgment |
-| --- | ------------------------- | ------: | ---------: | -------: |
-| 1   | prevention on              |      12 |          1 |        9 |
-| 1   | prevention off             |      19 |         14 |       22 |
-| 2   | full catalog, prevention on |    12 |          2 |        8 |
-| 2   | `Never` and `Code` only, prevention on | 12 |    3 |       11 |
-| 2   | prevention off             |      14 |         15 |        7 |
+Cleaning up a sloppy reply costs another request, and that request re-reads the whole conversation. On a 200k-token session the correction is more expensive than the paragraph it fixes.
 
-The mechanical result is established and replicated. Prevention takes them from 14 and 15 down to 1, 2 and 3, and the catalog that does it is the 117-token `Never` section: the reduced build carries the whole effect, so the other five prose sections are not what suppresses an em dash. These are the rules a machine can state exactly, and the model follows them when told.
+Most de-slopping tools work after generation: detect a tell, then ask a model to rewrite. Pi lets an extension return the system prompt for the turn through `before_agent_start`, which runs before the first token exists. That hook is why this is a pi extension rather than a filter.
 
-The judgment result is not established, and this table contradicts the earlier reading of it. Run 1 put judgment tells at 9 against 22 and looked like a 22 percent improvement per 1,000 characters. Run 2 put them at 8 and 11 against 7, which is no effect in either direction. The first reading came from normalising by length across arms that wrote different amounts; the second does not need that correction, and the honest summary is that the catalog's prose sections have no demonstrated effect on the tells this scanner can count.
+Two rules keep the injected block small:
 
-That is not evidence they are useless, because the scanner is blind to what they address. `Name the actor`, `Claims`, `Voice` and `Register` are about attribution, sourcing and register, and none of the 22 patterns looks for any of those. So the 660 tokens they cost, about two thirds of the injected block, are being measured by an instrument that cannot see their subject. Closing that needs either patterns that detect what the sections forbid, or a reader scoring the prose, and neither exists. Until then the number to watch is the mechanical one, which is real.
+- Constraints go in the prompt, procedures go behind a tool. "Never use an em dash" is short. A procedure for judging whether a paragraph is any good is long, and irrelevant on a turn that is not judging paragraphs.
+- Only rules that nothing else can enforce go in the prompt. Em dashes, curly quotes, `unknown` returns and 18 TypeScript rules have a deterministic check behind them, so restating them in the prompt buys the same enforcement twice.
 
-### A reader scoring the prose does not work either
+The injected block costs 208 tokens a request and the review guide 70. Pi marks the block cacheable, so a warm turn pays about a tenth. The block is computed once per project and frozen for the session: memory changes on every reply, and one changed word in the system prompt invalidates the whole cached prefix.
 
-The obvious way to measure the prose sections is to ask the model to read the prose, which is the one thing a regex cannot do. So: score both arms of the A/B with a question about the writing rather than the authorship. Not "was this machine-written", which is flat at chance above, but "how well does this paragraph hold a reader's attention and say something specific", on the scale `restsates what the reader already knows` to `earns every sentence it spends`.
+Set `PI_CACHE_RETENTION=long`. Pi's default cache TTL is 5 minutes, and any pause longer than that forces a full prefix rewrite.
 
-Ten replies per arm, 18,660 characters. Prevention on averaged 0.493 on the top criterion, prevention off 0.537. **AUC 0.390**, against chance at 0.500. The off arm scored slightly higher, which is the same below-chance result the authorship question gave, from a different angle.
+## Hooks
 
-That is four attempts on this checkpoint, three question shapes for authorship and a quality read on top, all at or below chance. The boundary is now clear enough to state: this checkpoint does coarse judgements about session state and does not do judgements about prose. The compaction question answers 0.8 or 0.013; the bulk-read relevance answer sits at 0.603 and is not flat. Nothing written about a paragraph has moved off chance.
+| Hook | What happens |
+| --- | --- |
+| `before_agent_start` | Injects the `Never` and `Code` sections of the catalog |
+| `tool_call` | Records the code files the turn touched, and notices a prose file once per session |
+| `tool_result` | Appends the tell report to a `write` or `edit` of a `.md`, `.mdx`, `.txt` or source file |
+| `message_end` | Measures the reply's tell density, silently |
+| `turn_end` | One oxlint spawn over everything the turn wrote, reported as a session entry |
 
-The relevance is not in question even though the measurement is. Every one of the 500 prose samples this project has recorded is prose over the 40-character floor, and 19 percent of them tripped a pattern, so this agent writes prose constantly and the sections describe prose it is producing. What is missing is any way to know whether it is following them.
+A write is never refused. Refusing it discards the tool call and the model regenerates the whole file, which costs more than the tell did. The report names the line, and a turn that ends on a write still gets its report because `turn_end` delivers it as an entry.
 
-So the honest accounting for the 660 tokens is this. They are not measured to help, and the instrument that could measure them is the one thing that does not work. They now sit in the on-demand guide rather than in front of every request, which is the middle option of the three: the rules still exist and still read the same, they just wait for `timbre_review_guide`. That took the injected block from 986 tokens to 326 and the suite's per-request overhead from about 3,627 to about 2,967.
+## Markdown
 
-### The 30 patterns that were removed, and why that is not the same gap
+| Moment | Catches |
+| --- | --- |
+| Before generation | Throat-clearing, hooks, upbeat closers, self-answered beats, summary paragraphs, title case, "leverage" |
+| On the write | Em and en dashes, clause-joining semicolons, curly quotes, tier-1 vocabulary, stock phrases |
+| On the result | Tool leakage (`utm_source=chatgpt.com`), zero-width characters, unfilled placeholders |
+| Statistics | Monotone cadence, four short sentences in a row, paragraphs that open the same way |
+| On demand | `/timbre fix <paths>` scans prose already on disk and makes the agent rewrite it |
 
-The scanner had 52 patterns. `37ec6428` cut 30 that had never fired, leaving the 19 measured ones plus three forensic catchers, and the reasoning at the time was that they cost a regex each per reply while measuring nothing.
+The report is advice, so there is a gate too. `bun scripts/prose-gate.mts` in this repository scans every tracked markdown file and fails on a tier-1 tell, and it runs inside `just check`. To use it in another repository, point its import at the installed package and call it from CI.
 
-That reasoning is weaker than it looks, because prevention was on for every sample behind it: all 500 prose samples this project had recorded were `prevented: true`, so a pattern for a tell the model had stopped producing could not have fired. Never firing is what a working guard looks like from the inside.
+Path sets the register without a model call. A changelog can be terse, a blog post cannot, and the same flat cadence is correct in one and wrong in the other. Code spans, fenced blocks, URLs and link targets are masked, so a document that quotes a tell is not committing it. The escape hatch is `<!-- lint-disable -- <reason> -->` in the first 400 bytes, and the reason has to say why.
 
-Re-testing them settled it anyway, twice. Scoring both arms of the run above with all 30 restored, across 24 replies and about 20,000 characters of technical prose, **not one of them fired in either arm**.
+## TypeScript
 
-The obvious objection is that this workload never writes an essay, so of course the essay patterns are quiet, and this repository does have a `prose` skill for exactly that. So the second test asked for the genre directly: five article-shaped prompts per arm, a blog post arguing for deletion, an opinion piece on estimates, a reflective post on trunk-based development, an article opening against on-call heroics, and a piece on error messages. Ten replies, about 14,000 characters, prevention on and off. **Zero of the 30 fired again.** The only patterns that fired were `em-dash` and `semicolon`, both of which are still in the set.
+Regexes cannot see `Promise<unknown>`, so that half is `dmmulroy/anti-slop`: 18 Oxlint rules, one run at the end of the turn over every source file the turn wrote.
 
-That is two independent corpora and 10,703 recorded samples with the same answer. They target essayistic tells: `rhetorical-hook`, `stock-opener`, `upbeat-closer`, `strawman-objection`, `fractal-summary`, `question-heading`. Ten replies is a thin sample on its own, but asking for the genre and getting silence is a stronger signal than never asking. The removal stands, and the honest reason is narrower than "they measure nothing": they measure a genre that does not appear here even when requested.
+| Rule | What it stops |
+| --- | --- |
+| `no-unknown-returns`, `no-unknown-parameters`, `no-unknown-type-aliases` | Hiding a value behind `unknown` |
+| `no-known-value-widening`, `no-widen-then-assert`, `no-chained-type-assertions` | Widening evidence and asserting it back |
+| `no-unsafe-dictionary-type`, `no-object-parameters`, `no-runtime-typeof` | Skipping the parse at the boundary |
+| `no-reflect-get`, `no-reflect-apply`, `no-conditional-empty-object-spread` | Untyped access, an unmodelled omission |
+| `require-safety-comment-for-type-assertion` | An assertion without a `SAFETY:` line |
 
-So the blindness above is real but it is not a broken instrument. The two claims are different. The 660 tokens teach rules for prose this agent does not write, which is a question about the catalog, and it is why they moved to the guide. The scanner's missing patterns would detect those rules in a genre that does not appear here, which is a question about nothing.
+The prompt and the linter do different jobs. The prompt tells the model what a good type looks like while it composes, and the linter supplies the evidence. A rule the linter can prove needs no prompt tokens, so the catalog's `Code` section is four lines.
 
-## Configuration
+The check runs once per turn because an oxlint spawn is about 130ms of fixed cost and a file adds 2 to 3ms. Forty files measured 230ms against 135ms for one. Two earlier arrangements failed: a follow-up note cost a whole model request, and a note attached to the next write result was dropped when the turn's last act was the write.
 
-| Variable            | Default | Meaning                                                                                                                                                       |
-| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TIMBRE`            | `1`     | Master switch                                                                                                                                                 |
-| `TIMBRE_PREVENT`    | `1`     | Layer 0. `0` measures without injecting                                                                                                                       |
-| `TIMBRE_WATCH_CHAT` | `1`     | Measure assistant replies, silently                                                                                                                           |
+## Setting up anti-slop
 
-Set `PI_CACHE_RETENTION=long` in your environment. Pi's default cache TTL is 5 minutes. Any pause longer than that forces a full prefix rewrite on the next turn.
+Upstream publishes no npm package and asks to be vendored, so timbre ships the vendoring:
 
-## Memory and adaptation
+```bash
+# from the installed package or any checkout of this repo
+./scripts/anti-slop-setup.sh
+```
 
-One JSON file per project lives under `$XDG_STATE_HOME/timbre/`, keyed by a hash of the project path. The file holds a rolling window of up to 500 samples plus any live overrides set by `/timbre`. Writes are atomic (temp file, then rename), and two sessions in one repository merge rather than lock: a simultaneous write can still drop one sample, which is cheap next to a lock file that strands the extension.
+The script fetches the pinned upstream revision and writes `~/.agents/tools/oxlint/anti-slop/` and `anti-slop.config.ts` with all 18 rules selected. It records provenance in `anti-slop.vendor.json`, installs `@oxlint/plugins` at the version your Oxlint reports, and then proves the rules run by checking a file that must fail. Re-running changes nothing unless you pass `--force`.
 
-A persisted setting outlives the session that set it. On session start, timbre reads the state file, loads any carried-over overrides, and announces the ones that differ from the env default. A subagent shares no memory with its parent session, only this file, so the state file is the only channel a `/timbre off` toggle has to reach it.
+Timbre reads that path by default. With the rules elsewhere:
 
-The prevention block is computed once per project and frozen for the session. Memory changes on every reply and every file write, so the block would shift mid-session. One changed word in the system prompt invalidates the entire cached prefix. Frozen, timbre adapts across sessions, which is the timescale a writing habit moves on.
+```bash
+export TIMBRE_OXLINT_CONFIG=./tools/oxlint/oxlint.config.ts
+export TIMBRE_OXLINT_BIN=./node_modules/.bin/oxlint   # optional, found automatically
+```
 
-## Register classification
+The same config is the hard gate. `just check` here runs `oxlint --config scripts/oxlint/anti-slop.config.ts extensions/`, and a project's pre-commit hook or CI can run the same command. The report is a tendency. The gate is what makes it never.
 
-A commit message, an API reference, and a blog post do not share a correct voice. Path classifies the register, with no model call:
+If upstream's own installer is a better fit, `npx skills add dmmulroy/anti-slop --skill install-anti-slop` vendors into the repository and merges the plugin into the project's Oxlint config. Point `TIMBRE_OXLINT_CONFIG` at that config, since timbre runs `oxlint --config` and reads the `anti-slop(...)` diagnostics back.
 
-| Path pattern                                                                           | Register  | Terse is correct | Voice allowed |
-| -------------------------------------------------------------------------------------- | --------- | ---------------- | ------------- |
-| `blog/`, `posts/`, `essays/`, `drafts/`                                                | narrative | no               | yes           |
-| `CHANGELOG.md`, `HISTORY.md`, `RELEASE_NOTES.md`, `COMMIT_EDITMSG`                     | changelog | yes              | no            |
-| `adr/`, `rfc/`, `spec/`, `reference/`, `api/`, `docs/`, `README.md`, `CONTRIBUTING.md` | reference | yes              | no            |
-| anything else                                                                          | unknown   | no               | no            |
+## Commands
 
-The register determines how the rhythm signal is interpreted. A flat cadence in a changelog is correct. The same cadence in a blog post is a tell.
+```
+/timbre status|stats
+/timbre on|off
+/timbre fix <paths>
+/timbre reset
+ctrl+alt+t
+```
 
-## Rhythm detection
+`/timbre` reports whether the design is holding: average cache read and write per turn, and a warning when writes dominate reads. It prints a measured effect after the project has samples from both prevention arms, so run `/timbre off` for a stretch first. Until then the effect reads `null`.
 
-Layer 2 adds two signals the regex patterns cannot see:
+A toggle persists to the project state file, so it survives the session and reaches a subagent, which runs as its own process.
 
-- Monotone cadence: uniform sentence lengths across the whole piece. Fires only when fewer than 30% of non-empty lines are structured (lists, headings) and the piece has at least one blank line, so technical docs stay quiet.
-- Staccato run: four or more short sentences in a row. One short sentence is emphasis. A run is engineering.
+## Measurements
 
-Both are suppressed for registers where terse and even cadence is correct (reference, changelog, chat).
+Prevention takes em dashes and semicolon chains from 14 and 15 per 1,000 characters down to 1, 2 and 3. The 117-token `Never` section carries that whole effect.
 
-## What it does not do
+The judgment sections have no demonstrated effect on the tells the scanner counts, and two runs disagree with the first reading. The scanner is blind to attribution and sourcing, the work those sections do, so it cannot measure them either way. They sit behind the tool for that reason.
 
-- Does not rewrite text after generation (prevention replaces cleanup).
-- Does not use a corpus or model call for detection (deterministic regex). A local model asked which of two passages reads more machine-generated picked the same one in both orderings, and one asked to label a whole file read human and machine text at chance over 80 passages, so nothing here is blocked or detected on one.
-- Does not recompute the prompt block per turn (frozen once, adapts across sessions).
+No model is used to detect anything. A local model asked which of two passages reads more machine-generated picked the same one in both orderings, and one asked to label a file read human and machine text at chance over 80 passages.
 
-Everything fails open: a broken scan or unwritable state leaves the turn untouched, and `/timbre` names a missing `guidance/` directory rather than reporting "prevention on" over an empty block.
+## Limits
 
-The code check needed the same treatment and did not have it. Both its inputs live outside this package: the `oxlint` binary is a dependency, but the rules are read from `~/.agents/tools/oxlint/anti-slop.config.ts` by absolute path, and they are not in `files`. A spawn whose config is missing returns `null`, which is indistinguishable from a clean file, so on any machine without that directory the check reported nothing and said nothing. `/timbre` now names a missing binary or a missing rule config, which is the only reason to notice. A published install still has no rules of its own: it degrades to the prompt block and says so.
+- Nothing is rewritten after generation.
+- Patterns are English. A French or Vietnamese repository gets the prompt block and little else.
+- Everything fails open. `/timbre` names a missing catalog, a missing Oxlint binary or a missing rule config instead of reporting prevention over an empty block.
 
 ## Install
 
@@ -155,3 +120,11 @@ pi install npm:@tduyng/pi-timbre
 ```
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-timbre`
+
+Then vendor the code rules once:
+
+```bash
+/path/to/extensions/pi-timbre/scripts/anti-slop-setup.sh
+```
+
+Design notes live in `src/README.md`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-timbre",
-  "version": "0.0.2",
-  "description": "Constrain the agent prose and code before it is written: inject the rules, block the undeniable tells, measure the reply, and rewrite what is already on disk.",
+  "version": "0.0.4",
+  "description": "Constrain prose and code before it is written: inject the rules, report the mechanical tells on the write, and check TypeScript against dmmulroy/anti-slop once per turn.",
   "keywords": [
     "pi",
     "pi-package",
@@ -25,6 +25,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "scripts",
     "README.md",
     "LICENSE"
   ],

package/scripts/anti-slop-setup.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Vendor dmmulroy/anti-slop where pi-timbre looks for it, and prove the rules run.
+#
+#   ./anti-slop-setup.sh              install the pinned revision into ~/.agents/tools/oxlint
+#   ./anti-slop-setup.sh --ref main   track upstream head instead of the recorded revision
+#   ./anti-slop-setup.sh --dir ./tools/oxlint   install beside a project
+#   ./anti-slop-setup.sh --force      replace a copy that is already there
+#
+# Upstream publishes no npm package and asks to be vendored, so there is nothing to depend on.
+# This writes the copy, the config that selects the rules, the provenance record, and a
+# one-line check that a known violation is reported. Re-running without --force changes nothing.
+set -euo pipefail
+
+REPO="https://github.com/dmmulroy/anti-slop"
+PINNED="c44ef22ca116d0ba62a3ff663a0bd13a3f3fa40b"
+REF="$PINNED"
+DEST="$HOME/.agents/tools/oxlint"
+FORCE=0
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --ref) REF="${2:?--ref needs a revision}"; shift 2 ;;
+        --dir) DEST="${2:?--dir needs a path}"; shift 2 ;;
+        --force) FORCE=1; shift ;;
+        -h|--help) sed -n '2,9p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+        *) echo "unknown argument: $1" >&2; exit 2 ;;
+    esac
+done
+
+DEST="${DEST/#\~/$HOME}"
+PLUGIN="$DEST/anti-slop"
+CONFIG="$DEST/anti-slop.config.ts"
+
+if [ -e "$PLUGIN" ] && [ "$FORCE" -eq 0 ]; then
+    echo "anti-slop is already installed at $PLUGIN"
+    echo "pi-timbre reads $CONFIG, so there is nothing to do. Re-run with --force to replace it."
+    exit 0
+fi
+
+need() { command -v "$1" >/dev/null 2>&1 || { echo "missing $1" >&2; exit 1; }; }
+need curl
+need tar
+need python3
+
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+echo "fetching anti-slop@$REF"
+curl -sfSL "$REPO/archive/$REF.tar.gz" | tar xz -C "$tmp"
+src=$(find "$tmp" -maxdepth 2 -type d -name src | head -1)
+[ -n "$src" ] || { echo "no src/ in the archive: upstream layout changed" >&2; exit 1; }
+
+mkdir -p "$DEST"
+rm -rf "$PLUGIN"
+cp -R "$src" "$PLUGIN"
+cp "$(dirname "$src")/LICENSE" "$DEST/anti-slop.LICENSE"
+
+oxlint_version="1.90.0"
+for candidate in "$(command -v oxlint || true)" "$PWD/node_modules/.bin/oxlint"; do
+    if [ -n "$candidate" ] && [ -x "$candidate" ]; then
+        found=$("$candidate" --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true)
+        [ -n "$found" ] && oxlint_version="$found" && OXLINT="$candidate"
+        break
+    fi
+done
+
+cat >"$DEST/package.json" <<JSON
+{
+  "name": "anti-slop-oxlint",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@oxlint/plugins": "$oxlint_version"
+  }
+}
+JSON
+
+python3 - "$REPO" "$REF" "$PLUGIN" "$DEST/anti-slop.vendor.json" <<'PY'
+import datetime, json, pathlib, sys
+repo, ref, plugin, out = sys.argv[1:5]
+pathlib.Path(out).write_text(json.dumps({
+    'name': 'anti-slop',
+    'repo': repo,
+    'license': 'MIT',
+    'licenseFile': 'anti-slop.LICENSE',
+    'upstreamPath': 'src',
+    'localPath': 'anti-slop',
+    'ref': ref,
+    'syncedAt': datetime.date.today().isoformat(),
+}, indent=2) + '\n')
+rules = sorted(set(__import__('re').findall(r'"([a-z0-9-]+)":', (pathlib.Path(plugin) / 'index.ts').read_text())))
+if not rules:
+    sys.exit('no rules found in anti-slop/index.ts: upstream layout changed')
+lines = ['// Written by pi-timbre scripts/anti-slop-setup.sh. Rules come from dmmulroy/anti-slop,',
+         '// vendored at ./anti-slop. Select a rule here to enforce it, and edit freely: this file',
+         '// is yours, not upstream.',
+         'export default {',
+         "    jsPlugins: [{ name: 'anti-slop', specifier: './anti-slop/index.ts' }],",
+         '    rules: {']
+lines += [f"        'anti-slop/{r}': 'error'," for r in rules]
+lines += ['    }', '}', '']
+pathlib.Path(out.replace('.vendor.json', '.config.ts')).write_text('\n'.join(lines))
+print(f"wrote {out.replace('.vendor.json', '.config.ts')} with {len(rules)} rules")
+PY
+
+(cd "$DEST" && { bun install --silent >/dev/null 2>&1 || npm install --silent --no-audit --no-fund >/dev/null 2>&1 || echo "install @oxlint/plugins in $DEST yourself: the rules import it" ; })
+
+probe="$tmp/probe.ts"
+printf 'type Values = unknown\nexport const values: Values = 1\n' >"$probe"
+if [ -n "${OXLINT:-}" ]; then
+    # oxlint exits 1 when it finds a violation, which is the expected result here.
+    out=$(cd "$DEST" && "$OXLINT" --config "$CONFIG" "$probe" 2>&1 || true)
+    if printf '%s' "$out" | grep -q 'anti-slop(no-unknown-type-aliases)'; then
+        echo "verified: $OXLINT reports an anti-slop violation through $CONFIG"
+    else
+        echo "installed, but the probe was not reported. Check @oxlint/plugins in $DEST" >&2
+        exit 1
+    fi
+else
+    echo "installed. No oxlint on PATH, so the probe was skipped."
+fi
+
+echo
+echo "pi-timbre reads $CONFIG by default. From another location, export:"
+echo "  TIMBRE_OXLINT_CONFIG=$CONFIG"

package/src/README.md

@@ -34,7 +34,7 @@ skills now live only under Claude Code, which has its own skill loader for them.
 ```
 before_agent_start   ->  inject the whole constraint set, plus what this project repeats
 timbre_review_guide  ->  serve the judgment procedure when the agent asks for it
-tool_call            ->  block writes carrying an undeniable tell before they land
+tool_call            ->  record the touched code, and notice a prose file once per session
 message_end          ->  measure the reply, silently, record what still got through
 tool_result          ->  report tells in prose and source files just written
 /timbre fix          ->  scan prose already on disk and make the agent rewrite it
@@ -49,7 +49,7 @@ that says whether prevention works.
 | Layer          | Detects                                                                                                                                                                                                                                                                                                                                                        | Cost                               |
 | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
 | 0. Prevention  | Nothing. Constrains the generation instead.                                                                                                                                                                                                                                                                                                                    | one cached system-prompt block     |
-| 0.5 Preflight  | Blocks the tells with no legitimate use and no false positive after masking: tool leakage, invisible Unicode, em and en dashes, curly quotes, a clause-joining semicolon. Everything else is note-only, placeholders included, since templates legitimately contain them. After three consecutive blocks it stands down rather than loop with a stubborn retry | free                               |
+| 0.5 Write report | Reports the tells a write would land, grouped by id and line, on the tool result. Nothing is refused: a refused write is discarded and regenerated, which costs more than the tell it prevented | free                               |
 | 1. Forensic    | Tool leakage: `utm_source=chatgpt.com`, `citeturn0search0`, zero-width characters, unfilled placeholders                                                                                                                                                                                                                                                       | free                               |
 | 1. Mechanical  | Fixed tells: dashes, semicolons, tier-1 vocabulary, stock phrases, Claude's own tics                                                                                                                                                                                                                                                                           | free                               |
 | 2. Statistical | Cadence, clause stacks, and paragraph shape: the signals regex cannot see                                                                                                                                                                                                                                                                                      | free                               |
@@ -127,8 +127,8 @@ sends the rewrite when the file carries no mechanical tell, because "are there t
 "is this any good" are different questions and the second one was asked.
 
 The check on the rewrite needs no extra machinery. The agent's edits go back out through
-`write` and `edit`, where the preflight blocks a reintroduced em dash, curly quote or
-semicolon outright and the tool result reports whatever else survived. An on-request scan
+`write` and `edit`, where the tool result reports a reintroduced em dash, curly quote or
+semicolon with its line. An on-request scan
 records no sample: a sample answers whether prevention changed what a model generated on
 some turn, and a file read off disk belongs to no turn and neither prevention arm, so
 counting it would corrupt the only measurement `/timbre` exists to produce.
@@ -186,6 +186,14 @@ Environment only.
 | `TIMBRE`            | `1`     | Master switch                                                                                          |
 | `TIMBRE_PREVENT`    | `1`     | Layer 0. `0` measures without injecting                                                                |
 | `TIMBRE_WATCH_CHAT` | `1`     | Measure assistant replies, silently                                                                    |
+| `TIMBRE_OXLINT_CONFIG` | `~/.agents/tools/oxlint/anti-slop.config.ts` | The rules the turn-end code pass runs. `scripts/anti-slop-setup.sh` writes a working one |
+| `TIMBRE_OXLINT_BIN` | the project's `node_modules/.bin/oxlint`, else the package's own | Which Oxlint the code pass spawns |
+
+The code pass is `dmmulroy/anti-slop`, vendored rather than depended on because upstream
+publishes no package. `scripts/anti-slop-setup.sh` fetches the pinned revision, writes the
+copy, the selecting config, the provenance record, and verifies the rules by checking a file
+that must fail. The same config serves a project's hard gate, which is the only thing that
+makes "never" true: timbre reports, the gate refuses to merge.
 
 Set `PI_CACHE_RETENTION=long` in your environment. Pi's default cache TTL is 5 minutes, so
 any pause longer than that makes the next turn re-write the whole cached prefix instead of
@@ -293,19 +301,13 @@ flagged lines into contiguous spans and computes the flagged character fraction,
 `/timbre fix` can say "lines 40-58 are machine-shaped, rewrite from your outline" rather
 than deliver a scattered list.
 
-**A weak model argues with a note, so the typography tells block instead.** Layers 0 and 1
-both route through the model's cooperation: the prompt asks, the report tells. A
-`nemotron-3.5-lightning-free` session put twenty em dashes in one document with the rule in
-its system prompt, read the report naming every line, and concluded the detector was wrong.
-A block is the one enforcement that does not need the model to agree, so the tells that
-cannot be a false positive after masking take that path. The rest stay notes, because a
-wrongly blocked write costs a full retry round trip.
+**A blocked write costs more than the tell it prevents.** An earlier version refused a write carrying an em dash, a curly quote or a clause-joining semicolon, on the argument that a weak model argues with a note. A `nemotron-3.5-lightning-free` session put twenty em dashes in one document with the rule in its system prompt, read the report naming every line, and concluded the detector was wrong, which is the case a block fixes. It was still dropped: the refusal discards the tool call, the model regenerates the whole file, and the same text arrives in the same report the block replaced. Reporting on the result names the path and every line, and the model fixes it without a regeneration.
 
-**The block groups by id, not by hit.** Seven em dashes used to print seven identical hint
+**The report groups by id, not by hit.** Seven em dashes used to print seven identical hint
 lines and no location, which reads as noise and leaves the agent guessing which spans to
-rewrite. The message now names the path, one line per id with every line number it fired on,
+rewrite. The message names the path, one line per id with every line number it fired on,
 and the first two offending lines quoted. An edit's numbers count the hunk text rather than
-the file, and the message says so, since `edits[].newText` is all the preflight sees.
+the file, and the message says so, since `edits[].newText` is all timbre sees.
 
 **A write scans the whole file. An edit scans only its hunks.** Both come straight from the
 tool call, never a disk read. `write` always replaces a file wholesale, so the whole new file
@@ -364,8 +366,11 @@ and the forensic tier, and little else of value.
 | `stats.ts`               | Layer 2. Burstiness                                                    |
 | `register.ts`            | Path to register classification                                        |
 | `prevent.ts`             | Layer 0. Composes the block and the recurring-tells line               |
+| `code.ts`                | The turn-end Oxlint anti-slop pass and its rules config                 |
 | `memory.ts`              | Layer 4. Per-project state and the effect calculation                  |
 | `report.ts`              | Formatting for the model and for the terminal                          |
+| `segments.ts`            | Merges adjacent flagged lines into one span to rewrite                 |
+| `config.ts`              | Environment switches                                                   |
 | `index.ts`               | Event wiring                                                           |
 
 ## Development

package/src/code.ts

@@ -11,6 +11,8 @@ import { t } from 'ata-validator/t'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 function findOxlintBin(): string {
+    const project = join(process.cwd(), 'node_modules', '.bin', 'oxlint')
+    if (existsSync(project)) return project
     let dir = HERE
     while (true) {
         const candidate = join(dir, 'node_modules', '.bin', 'oxlint')
@@ -20,9 +22,26 @@ function findOxlintBin(): string {
         dir = parent
     }
 }
-const OXLINT_BIN = findOxlintBin()
-const OXLINT_CONFIG = join(homedir(), '.agents', 'tools', 'oxlint', 'anti-slop.config.ts')
-const VENDORED = `${join(homedir(), '.agents', 'tools', 'oxlint')}/`
+const DEFAULT_CONFIG = join(homedir(), '.agents', 'tools', 'oxlint', 'anti-slop.config.ts')
+
+function envPath(name: string, fallback: string): string {
+    const raw = process.env[name]
+    if (raw === undefined || raw === '') return fallback
+    return isAbsolute(raw) ? raw : resolve(process.cwd(), raw)
+}
+
+export function oxlintBin(): string {
+    return envPath('TIMBRE_OXLINT_BIN', findOxlintBin())
+}
+
+export function oxlintConfig(): string {
+    return envPath('TIMBRE_OXLINT_CONFIG', DEFAULT_CONFIG)
+}
+
+/** The vendored plugin is synced from upstream, so a file the turn wrote inside it is not the model's. */
+function vendoredDir(config: string = oxlintConfig()): string {
+    return `${join(dirname(config), 'anti-slop')}/`
+}
 
 const TS_FILE = /\.(ts|tsx|js|jsx|mjs|cjs)$/i
 const SKIP_CODE = [
@@ -70,7 +89,7 @@ export function codePath(
     const path = String(event.input['path'] ?? '')
     if (!TS_FILE.test(path)) return null
     const abs = isAbsolute(path) ? path : resolve(cwd, path)
-    if (abs.startsWith(VENDORED)) return null
+    if (abs.startsWith(vendoredDir())) return null
     if (SKIP_CODE.some((re) => re.test(abs))) return null
     return abs
 }
@@ -88,7 +107,7 @@ export type CodeFinding = Hit & { path: string }
 // A spawn that cannot find its config returns null, which reads the same as a clean file, so
 // the failure is otherwise invisible. Both paths live outside this package: the rules are a
 // vendored copy under ~/.agents/tools/oxlint, so a checkout on another machine checks nothing.
-export function codeCheckProblem(bin: string = OXLINT_BIN, config: string = OXLINT_CONFIG): string | undefined {
+export function codeCheckProblem(bin: string = oxlintBin(), config: string = oxlintConfig()): string | undefined {
     if (!existsSync(bin)) return `the code check is off: no oxlint binary at ${bin}`
     if (!existsSync(config)) return `the code check is off: no rule config at ${config}`
     return undefined
@@ -96,8 +115,8 @@ export function codeCheckProblem(bin: string = OXLINT_BIN, config: string = OXLI
 
 export async function scanCodeBatch(
     paths: string[],
-    bin = OXLINT_BIN,
-    config = OXLINT_CONFIG
+    bin = oxlintBin(),
+    config = oxlintConfig()
 ): Promise<CodeFinding[] | null> {
     const unique = [...new Set(paths)].filter((path) => existsSync(path))
     if (unique.length === 0) return []