@tduyng/pi-timbre 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,178 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+Use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 tduyng

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# @tduyng/pi-timbre
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+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.
+
+## 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.
+
+| 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 |
+
+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 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.
+
+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.
+
+### 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 30 patterns that were removed, and why that is not the same gap
+
+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.
+
+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.
+
+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**.
+
+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.
+
+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.
+
+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.
+
+## Configuration
+
+| Variable            | Default | Meaning                                                                                                                                                       |
+| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TIMBRE`            | `1`     | Master switch                                                                                                                                                 |
+| `TIMBRE_PREVENT`    | `1`     | Layer 0. `0` measures without injecting                                                                                                                       |
+| `TIMBRE_WATCH_CHAT` | `1`     | Measure assistant replies, silently                                                                                                                           |
+
+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.
+
+## Memory and adaptation
+
+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.
+
+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.
+
+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.
+
+## Register classification
+
+A commit message, an API reference, and a blog post do not share a correct voice. Path classifies the register, with no model call:
+
+| 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 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.
+
+Both are suppressed for registers where terse and even cadence is correct (reference, changelog, chat).
+
+## What it does not do
+
+- 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).
+
+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.
+
+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.
+
+## Install
+
+```bash
+pi install npm:@tduyng/pi-timbre
+```
+
+Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-timbre`

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@tduyng/pi-timbre",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "writing",
+    "prose",
+    "lint",
+    "anti-slop"
+  ],
+  "homepage": "https://gitlab.com/tduyng/pi-agent/-/tree/main/extensions/pi-timbre#readme",
+  "bugs": "https://gitlab.com/tduyng/pi-agent/-/issues",
+  "license": "Apache-2.0",
+  "author": "tduyng",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/tduyng/pi-agent.git",
+    "directory": "extensions/pi-timbre"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "ata-validator": "^1.62.1",
+    "oxlint": "1.82.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}