@tduyng/pi-timbre 0.0.2 → 0.0.3

package/README.md

@@ -1,152 +1,112 @@
 # @tduyng/pi-timbre
 
-Constrains the agent's prose and code before tokens are generated, then measures what still gets through.
+Stop the slop before it is written. The rules go in the prompt, the mechanical tells are caught on the result, and the code is checked once at the end of the turn.
 
-For full design rationale, see `src/README.md`.
+## What it costs
 
-## 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.
+208 tokens of injected rules a request, and 70 for the review guide tool. Those rules sit in a cacheable block, so a warm turn pays about a tenth of that: pi marks the block cacheable, and the provider bills a cache read at a fraction of a write.
 
-`timbre_review_guide` tool: serves the judgment procedure on request.
+The rules cost less than the rewrite they prevent. A reply carrying three em dashes, a semicolon chain, and a summary paragraph costs a follow-up turn to fix, and that turn re-reads the whole prefix.
 
-`/timbre` subcommands: `on`, `off`, `fix <paths>`, `reset`, `status`, `stats`.
+Set `PI_CACHE_RETENTION=long`. Pi's default cache TTL is 5 minutes, so any pause longer than that forces a full prefix rewrite on the next turn.
 
-`ctrl+alt+t` shortcut: toggles prevention with the same persistence as the command. The status bar shows `on` or `off`.
+## What it adds
 
-## Token costs
+`before_agent_start` injects the `Never` and `Code` sections of the catalog into the system prompt. The five judgment sections wait in `timbre_review_guide`, which the model calls when it is about to review prose.
 
-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:
+`tool_result` appends a tell report to `write` and `edit` results for prose and TypeScript files. A write is never refused, because refusing it discards the tool call and costs a full regeneration, which is more than the tell it prevented is worth. One note per file per session.
 
-- 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
+`message_end` records tell density per reply, silently.
 
-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.
+`/timbre` takes `on`, `off`, `fix <paths>`, `reset`, `status`, and `stats`. `ctrl+alt+t` toggles prevention with the same persistence, and the status bar shows `on` or `off`.
 
-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.
+## The code check
 
-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.
+Code is checked once per turn, not once per write. An oxlint spawn costs about 130ms of fixed overhead and a file adds 2 to 3ms, so a per-write check paid that fixed cost 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.
 
-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.
+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 and replied that the reports were stale. Moved onto the next write or edit result, the note was unambiguous but dropped 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.
 
-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.
+An entry at the turn's end costs no model request, keeps its own provenance, and is always delivered. What remains is the deterministic report on the write and edit results, which covers the mechanical tells in the text the model wrote.
 
 ## What prevention is worth
 
-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.
-
-Mechanical tells are the em dashes, semicolons and invisible characters. Judgment tells are the wall paragraphs and the monotone cadence.
+Two runs, same model, scratch projects, replies scored by the deterministic scan.
 
-| 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 |
+| Run | Arm | Replies | Mechanical | Judgment |
+| --- | --- | ---: | ---: | ---: |
+| 1 | prevention on | 12 | 1 | 9 |
+| 1 | prevention off | 19 | 14 | 22 |
+| 2 | full catalog, on | 12 | 2 | 8 |
+| 2 | `Never` and `Code` only, on | 12 | 3 | 11 |
+| 2 | prevention off | 14 | 15 | 7 |
 
-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.
+The mechanical result is established and replicated. Prevention takes em dashes and semicolon chains from 14 and 15 down to 1, 2, and 3, and the 117-token `Never` section carries the whole effect, so the other prose sections are not what suppresses an em dash. These are rules a machine can state exactly, and the model follows them when told.
 
-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.
+The judgment result is not established, and this table contradicts an 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, so the honest summary is that the catalog's prose sections have no demonstrated effect on the tells this scanner counts.
 
-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.
+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 moved to the on-demand guide, which took the injected block from 986 tokens to 326 and the suite's per-request overhead from about 3,627 to about 2,967.
 
 ### A reader scoring the prose does not work either
 
-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`.
-
-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.
-
-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.
-
-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.
-
-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.
+The obvious instrument for those sections is the model itself. Ten replies per arm, 18,660 characters, scored not on authorship but on "how well does this paragraph hold a reader's attention and say something specific": prevention on averaged 0.493, off 0.537, AUC 0.390 against chance at 0.500.
 
-### The 30 patterns that were removed, and why that is not the same gap
+That is four attempts on this checkpoint and three question shapes on authorship, all at or below chance. The boundary is clear: this checkpoint does coarse judgements about session state and does not do judgements about prose. Nothing written about a paragraph has moved off chance.
 
-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 30 patterns that were removed
 
-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.
+The scanner had 52 patterns, and 30 that had never fired were cut. Never firing is what a working guard looks like from the inside, because prevention was on for every sample behind them, so the cut was re-tested twice.
 
-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**.
+With all 30 restored, across 24 replies and about 20,000 characters of technical prose, not one fired in either arm. Then the genre was asked for directly: five article-shaped prompts per arm, ten replies, about 14,000 characters, prevention on and off. Zero of the 30 fired again, and the only patterns that fired were `em-dash` and `semicolon`, both still in the set.
 
-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.
+They target essayistic tells (`rhetorical-hook`, `stock-opener`, `upbeat-closer`, `strawman-objection`, `fractal-summary`, `question-heading`), which is a genre that does not appear here even when requested. The removal stands.
 
-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.
+## Register
 
-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.
+A commit message, an API reference, and a blog post do not share a correct voice. Path classifies the register with no model call.
 
-## Configuration
+| 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 |
 
-| Variable            | Default | Meaning                                                                                                                                                       |
-| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TIMBRE`            | `1`     | Master switch                                                                                                                                                 |
-| `TIMBRE_PREVENT`    | `1`     | Layer 0. `0` measures without injecting                                                                                                                       |
-| `TIMBRE_WATCH_CHAT` | `1`     | Measure assistant replies, silently                                                                                                                           |
+The register decides how the rhythm signal reads. A flat cadence in a changelog is correct, and the same cadence in a blog post is a tell.
 
-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.
+## Rhythm
 
-## Memory and adaptation
+Two signals the regexes cannot see:
 
-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.
+- Monotone cadence: uniform sentence lengths across the piece. Fires only when fewer than 30 percent of non-empty lines are structured 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, and a run is engineering.
 
-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.
+Both are suppressed for the registers where an even cadence is correct.
 
-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.
+## Memory
 
-## Register classification
+One JSON file per project under `$XDG_STATE_HOME/timbre/`, keyed by a hash of the project path, holding up to 500 samples plus any live overrides from `/timbre`. Writes are atomic, and two sessions in one repository merge rather than lock: a simultaneous write can drop one sample, which is cheap next to a lock file that strands the extension.
 
-A commit message, an API reference, and a blog post do not share a correct voice. Path classifies the register, with no model call:
+A persisted setting outlives the session that set it. On session start timbre reads the file, loads the overrides, and announces the ones that differ from the environment default. A subagent shares no memory with its parent, only this file, so it is the only channel a `/timbre off` has to reach it.
 
-| 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            |
+The prevention block is computed once per project and frozen for the session, because memory changes on every reply and one changed word in the system prompt invalidates the whole cached prefix. Frozen, timbre adapts across sessions, which is the timescale a writing habit moves on.
 
-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.
-
-## Rhythm detection
-
-Layer 2 adds two signals the regex patterns cannot see:
-
-- 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.
+## What it does not do
 
-Both are suppressed for registers where terse and even cadence is correct (reference, changelog, chat).
+- It does not rewrite text after generation, since prevention replaces cleanup.
+- It does not call a model 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 whole file read human and machine text at chance over 80 passages.
+- It does not recompute the prompt block per turn.
 
-## What it does not do
+Everything fails open: a broken scan or an unwritable state leaves the turn untouched, and `/timbre` names a missing `guidance/` directory rather than reporting prevention on over an empty block.
 
-- 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).
+The code check degrades the same way. Its rules are read from `~/.agents/tools/oxlint/anti-slop.config.ts` by absolute path and are not in the published tarball, and a spawn whose config is missing returns null, which is indistinguishable from a clean file. `/timbre` now names a missing binary or a missing rule config, which is the only reason you would notice. A published install degrades to the prompt block and says so.
 
-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.
+## Configure
 
-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.
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `TIMBRE` | `1` | Master switch |
+| `TIMBRE_PREVENT` | `1` | Layer 0. `0` measures without injecting |
+| `TIMBRE_WATCH_CHAT` | `1` | Measure assistant replies, silently |
 
 ## Install
 
@@ -155,3 +115,5 @@ pi install npm:@tduyng/pi-timbre
 ```
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-timbre`
+
+The full design rationale lives 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.3",
+  "description": "Constrain prose and code before it is written: inject the rules, catch the mechanical tells, check the code once per turn.",
   "keywords": [
     "pi",
     "pi-package",