@tduyng/pi-timbre 0.0.0-stage → 0.0.2

package/src/README.md

@@ -0,0 +1,385 @@
+<!-- lint-disable -- this file quotes the tells it documents -->
+
+# timbre
+
+Keeps the agent's prose and code sounding like this project, by constraining it before the
+tokens are generated rather than cleaning up after.
+
+Timbre is the acoustic property that identifies a specific voice regardless of pitch or
+volume. That is the target here: not "generic human prose" but prose that still sounds like
+the person whose repository it lands in.
+
+## Why this is not another slop linter
+
+Every comparable tool works after generation.
+
+| Tool                | Detection                    | Correction                       | Cost per reply          |
+| ------------------- | ---------------------------- | -------------------------------- | ----------------------- |
+| SLYE                | none, 200-char gate          | secondary LLM rewrite            | 1 API call              |
+| claudish-to-english | none, 200-char gate          | local ollama rewrite             | 1 local call            |
+| nopus               | statistical, corpus-backed   | asks the agent to redo the reply | 1 redo                  |
+| humanizer           | none, on demand              | the agent, against 50+ patterns  | free                    |
+| timbre              | deterministic, then measured | prevention, before generation    | one cached prompt block |
+
+Pi's `before_agent_start` can return a system prompt for the turn. That is the one hook that
+makes prevention possible, and it is why this extension is Pi-only. Nothing else in the
+comparison table can reach the other side of generation.
+
+For Pi, timbre replaces the `prose` skill outright. It carries the full
+rule set: the constraints in the system prompt, the judgment layer behind a tool. Those two
+skills now live only under Claude Code, which has its own skill loader for them.
+
+## The loop
+
+```
+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
+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
+memory               ->  feeds the next before_agent_start
+```
+
+Detection is not a separate product here. It is the input to prevention and the instrument
+that says whether prevention works.
+
+## Layers
+
+| 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                               |
+| 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                               |
+| 3. Judgment    | Triage, the pattern catalog, false positives, human signals worth keeping                                                                                                                                                                                                                                                                                      | one tool call, only when reviewing |
+
+There is no corpus. nopus reaches layer 2 with 1.8 MB of frequency and concreteness data,
+which overlaps heavily with the tier-1 vocabulary already matched exactly. Cadence variance,
+clause stacks, repeated openings, and paragraph shape need no data at all, so they are the
+signals implemented.
+
+Tier 2 words (`robust`, `seamless`, `pivotal`, `harness`) are not flagged one by one.
+They are ordinary English alone and a tell only in clusters, so timbre counts them per
+paragraph and flags a paragraph that uses several at once. That catches the cluster without
+the single-use false positives that would discredit the report.
+
+## The Pangram method
+
+Detection and rewrite rules draw from the Pangram 4 technical report (Glickenhaus et al.,
+2026): clause-level provenance, contiguous span aggregation, and the rule that reordering
+your own sentences never changes authorship but rewording toward model phrasing does.
+
+## Register
+
+A commit message, an API reference and a blog post do not share a correct voice. Terse and
+list-heavy is right in a changelog and wrong in an essay, so the rhythm signal has to mean
+different things in each. Path classifies it, with no model call:
+
+| Path                                 | Register  | Terse is correct | Voice allowed |
+| ------------------------------------ | --------- | ---------------- | ------------- |
+| `docs/`, `README.md`, `adr/`, `api/` | reference | yes              | no            |
+| `CHANGELOG.md`, `COMMIT_EDITMSG`     | changelog | yes              | no            |
+| `blog/`, `posts/`, `essays/`         | narrative | no               | yes           |
+| anything else                        | unknown   | no               | no            |
+
+## Commands
+
+A status indicator in the bar shows the live mode (`timbre: on`, `timbre: off`).
+
+| Command                                | Effect                                                                                                          |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `/timbre`                              | Tell density with prevention on versus off, the most frequent tells, and where each setting comes from          |
+| `/timbre fix <path>... [instructions]` | Scan prose already on disk and make the agent rewrite it. The way back into a document layers 0 and 1 never saw |
+| `/timbre off`                          | Stop injecting. Samples still record, which is how a baseline gets built                                        |
+| `/timbre on`                           | Resume injecting                                                                                                |
+| `/timbre reset`                        | Discard this project's samples, live overrides included, back to the env defaults                               |
+| `ctrl+alt+t`                           | Toggle prevention with the same persistence path as `/timbre on` and `/timbre off`                              |
+
+`/timbre fix` is the repair path for text that already landed. Layers 0 and 1 both act at
+generation time, so a document written in an earlier session, by another tool, or by a model
+that ignored the rules is out of their reach entirely. `fix` scans the named files off disk,
+groups what it finds by tell id with the line numbers, and sends the agent a real user
+message that starts a turn. It sends nothing when a file scans clean, and it skips a file
+carrying a `<!-- lint-disable -- <reason> -->` marker, the same escape hatch the write path honours.
+
+A word names a file when it starts with the `@` file completion inserts, carries a glob
+character, ends in a prose suffix, or is path-shaped and exists on disk. Everything else is
+instruction text, kept verbatim with its newlines, and it rides along in the rewrite request.
+That last clause is what keeps a pasted paragraph mentioning `JSON.parse` or `/someEndpoint`
+from being read as two files nobody asked for.
+
+Globs expand here, since a slash command is not a shell and nothing expanded them on the way
+in. A pattern without a directory in it searches the whole project, so `/timbre fix *.md drop
+the ai slop` reaches `docs/deep.md`. One with a directory is taken literally. `node_modules`,
+`.git` and the usual build directories are never walked. One request carries at most ten
+files and says how many it left behind.
+
+Naming no file at all is allowed. `/timbre fix that readme and shorten it` refers to a file
+the way a person does, and resolving that needs the conversation, which the command handler
+cannot see and the agent already has. So the sentence is forwarded intact, with the review
+procedure attached, and the agent finds the file. Nothing is scanned on that path: no line
+numbers up front, and the agent runs the scan itself once it knows what it is looking at.
+
+An instruction also overrides a clean scan. `/timbre fix notes.md make it shorter` still
+sends the rewrite when the file carries no mechanical tell, because "are there tells" and
+"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
+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.
+
+`on` and `off` switch live, take effect the next turn, and persist
+to the project state file: a one-off `/timbre off` for this session is also what the next,
+unrelated session in this project starts from, not something scoped back down when the
+session ends. Each switch says so (`project default until changed again`), and each also
+changes the system prompt, so it says the next turn re-primes the cached prefix rather than
+reusing this turn's cache read. `/timbre reset` is the way back to `TIMBRE_PREVENT` and
+`TIMBRE_PREVENT`'s env value. `ctrl+alt+t` toggles prevention with the
+same persistence path as `/timbre on|off`, for flipping mid-session without leaving the editor.
+
+Persisting to the file rather than keeping the switch session-scoped is what lets it reach a
+subagent: a subagent runs as its own `pi` process against the same project, sharing no memory
+with the session that spawned it, so the state file is the only channel `/timbre off` has to
+reach it. `TIMBRE_PREVENT` set in the environment reaches subagents too, since they inherit
+it. Only the live toggle needed the file.
+
+A persisted toggle outlives the session that set it, so a new session announces any still-active override at startup instead of applying it silently, and `/timbre` names each setting's source (env or the state file) and flags carry-overs. The announcement names only overrides that change behaviour against the env default: a `/timbre off` on a session whose `TIMBRE_PREVENT` is already `0` is not news.
+
+## Does prevention work
+
+That is an empirical question, answered by `/timbre` rather than argued about. Every sample
+records whether layer 0 was active, so the readout compares this project's own
+prevention-on and prevention-off history directly. Until both arms have samples the effect
+reads `null`:
+
+```
+  prevention off: no samples yet (run /timbre off to build a baseline)
+  prevention on:  <density> tells/1k chars over <n> samples
+
+  Effect: null (need samples from both arms)
+```
+
+To get a real number, run `/timbre off` for a stretch, then `/timbre on`. Once both arms have
+samples the readout prints a measured delta:
+
+```
+  prevention off: <density> tells/1k chars over <n> samples
+  prevention on:  <density> tells/1k chars over <m> samples
+
+  Effect: <Z>% fewer tells with prevention on.
+```
+
+`<Z>` is filled from real samples, never estimated. No project has a two-sided sample set
+yet, so no percentage has been measured or quoted as timbre's actual effect.
+
+## Configuration
+
+Environment only.
+
+| 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, so
+any pause longer than that makes the next turn re-write the whole cached prefix instead of
+reading it, at 12x the cost. A 1-hour TTL is what makes the numbers below hold in practice.
+
+## What layer 0 costs
+
+The block sits in the system prompt, so it is sent on every turn of every session. It is built whenever prevention is on: a rule the model only meets after the write is a rule it already broke. Gating the block on the read also had a failure mode, since a refused connection and a model with nothing to say look the same from the outside, and the rules ended up nowhere with nothing reporting it. Pi marks the block cacheable, and Anthropic bills cache writes at 1.25x and reads at 0.1x:
+
+|                                          | tokens                                        |
+| ---------------------------------------- | --------------------------------------------- |
+| The catalog                                            | 986                                           |
+| Per turn, cache warm                     | 99                                            |
+| Per turn, cache cold                     | 1,085                                         |
+| `review.md`                              | 4,586, and only when the agent calls the tool |
+
+A 30-turn session costs about 5k tokens with a 1-hour cache. The same session costs 47k if
+every single turn goes cold, which is what a 5-minute TTL plus normal think time produces.
+
+That table is a computed estimate, not a measurement. `/timbre` now reports the average
+`cacheRead`/`cacheWrite` Anthropic itself billed per turn, straight from each reply's own
+`usage`, so the estimate can be checked against a real session rather than trusted on its own:
+
+```
+  cache (prevention on): avg 118 read / 3 write tokens/turn over 12 turns
+```
+
+A high write average relative to read means the prefix is not actually staying cached turn to
+turn, the one failure that would silently defeat the whole design, and `/timbre` says so.
+
+The catalog states the rules nothing else can enforce and omits the ones the scanner
+catches for free: paying every turn to restate a rule the tool result already names by line
+buys the same enforcement twice. `TIMBRE_PREVENT=0` drops the cost to zero and leaves
+detection and measurement running, which is the cheapest way to build a baseline before
+deciding whether prevention pays for itself.
+
+## Design constraints worth keeping
+
+**Every rule is enforced, not every rule is injected.** Coverage is a property of the whole
+system, not of the prompt. The tool result catches 22 prose tells, 18 TypeScript rules and the statistical
+tells for free,
+so those do not need prompt tokens to be enforced. What only prevention can reach is the rest:
+false agency, naming the real thing, fabrication, dropped caveats, register, discourse shape,
+and the code smells no linter sees. `catalog.md` states exactly that set, plus the handful of
+mechanical tells whose base rate is high enough that catching them after the fact would mean
+constant rewrite churn.
+
+**The block is static.** An earlier version varied per turn, which was the worst possible
+property for the one string that sits in front of the entire conversation.
+
+The block is computed once per project and then frozen for the session. Recomputing it per
+turn would be ruinous: memory changes on every reply and every file write, and the
+system prompt sits in front of the whole conversation, so one shifted word there invalidates
+the entire cached prefix. It still adapts across sessions, which is the timescale a
+writing habit actually moves on.
+
+**Constraints are injected, procedures are served.** A constraint ("never an em dash") is
+short and useless after the fact, so it belongs in the prompt before generation. A procedure
+for judging and repairing existing text is long and irrelevant on any turn that is not doing
+that, so it sits behind the `timbre_review_guide` tool. That split is what lets timbre carry
+the whole of `prose` and `anti-slop` without paying for the whole of it every turn.
+
+**Every tell is stated once in `patterns.ts`.** `guidance/catalog.md` is the only place a
+constraint's prose lives. `patterns.ts` carries detection regexes and nothing else. An earlier
+version paired each pattern with its own copy of the rule text, which made two sources of
+truth for the same sentence and a standing invitation to drift.
+
+**One catalog, chosen by nothing.** A regex over the prompt text used to pick between rule
+sets, scoring 0.375 recall at 0.250 precision over 17 recorded sessions, and the switch cost
+a live subcommand, a persisted setting, a compaction latch and a second cache signature.
+`catalog.md` is now injected on every turn, sent with the rewrite request and read by System
+One.
+
+Every section it states is a rule no detector checks: the actor, the real thing, the claim,
+the voice, the register, the code comment. Every section it omits has a detector behind it.
+Framing tells maps to six patterns, Structures to avoid to seven, Shape's cadence to the
+Tier-2 statistics, Conversation to `chat-artifact`, the TypeScript rules to the vendored
+word lists to `ai-vocabulary`. Two exceptions moved rather than
+vanished: the typographic ellipsis, which no pattern matches, sits in Never, and the line
+about justifying a type assertion with a type rather than a comment is absent, since
+`require-safety-comment-for-type-assertion` is enforced and the catalog would have been
+arguing with it.
+
+`review.md` stays separate. It is a procedure rather than a rule set, so it is served on
+demand.
+
+**Everything fails open, but a degraded state is never silent.** A broken scan, an unwritable
+state file or malformed memory leaves the turn exactly as Pi would have run it. File findings
+are appended to a successful tool result rather than raised as an error: the write did happen,
+and a false error sends the agent rewriting a file that is already correct on disk. Failing
+open is not the same as failing invisibly: a missing `guidance/` directory (a packaging slip)
+or an unreadable catalog both degrade a whole layer to a no-op, and `/timbre`
+names both rather than reporting "prevention on" over an empty block.
+
+**A hit is evidence, not a verdict.** Backtick spans, fenced and indented code, URLs and
+link targets are masked, so a doc naming a tell is not committing it. Markdown blockquotes
+and double-quoted phrases are **not** masked and will be flagged: the escape hatch there is
+`<!-- lint-disable -- <reason> -->` in the first 400 bytes, which is how this README avoids flagging itself.
+The reason must run at least 8 characters, and a bare marker is not honoured, so an opt-out
+always says why.
+
+**Spans over scattered hits.** Fifteen em dashes and a handful of throat-clearing phrases
+need the agent to know which line ranges are machine-shaped. `segments.ts` merges adjacent
+flagged lines into contiguous spans and computes the flagged character fraction, so
+`/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.
+
+**The block 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,
+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.
+
+**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
+is the agent's own text. `edit` carries `edits[].newText`, so a three-line change to a long
+document is judged on those three lines, not on every tell already sitting in the rest of the
+file. That also keeps a page under active edit from dominating the sample window with
+near-duplicate reads of its own unchanged bulk.
+
+## State
+
+One JSON file per project under `$XDG_STATE_HOME/timbre/`, keyed by a hash of the project
+path. Writes are atomic (temp file, then rename) so a crash mid-write cannot leave a
+truncated file that breaks the next session. Nothing leaves the machine. A prose write is
+noticed once per file per session, keyed by session and path, so a rewrite cannot spend a
+second notice on the same file. `/timbre` counts what was noticed and what was held back.
+
+## Known limits
+
+**Thesis still unverified by field data.** `index.test.ts` fires the real `before_agent_start`,
+`message_end`, and `tool_result` handlers the way Pi would, so the wiring is verified. The thesis, that preventing before generation reduces tells, is not
+verified: a project that has only ever run with prevention on has no baseline, so the effect
+reads `null`. A measured effect requires running `/timbre off` for a stretch first.
+
+**Calibration.** The burstiness threshold (CoV below 0.35 over 6+ sentences) is a starting
+value, not a derived one. nopus published intervention rates from 5,337 measured responses.
+Nothing here has that backing yet, which is precisely what `/timbre` exists to produce.
+
+**Measurement caveats that survive.** Hits are counted once per pattern per line, so a hard
+wrapped paragraph scores higher than the same text unwrapped. Chat replies are never
+wrapped and file prose usually is, so the two are not perfectly comparable even within the
+prose domain. Concurrent sessions merge on write rather than lock, so a simultaneous write
+can still drop one sample.
+
+**Pattern rot.** Every pattern is calibrated against current models. Wikipedia's own guide
+already notes some signs are outdated for recent releases. Patterns live in `patterns.ts` as
+data for that reason.
+
+**Corpus contamination, if voice learning is ever added.** Learning an author's voice from a
+git history that already contains model-written commits teaches the system to reproduce slop
+as "their voice". A clean corpus would mean pre-2023 commits or explicitly human-verified
+text. Getting this wrong inverts the product silently, so it is not implemented on a guess.
+
+**English only.** The pattern list is English. A French or Vietnamese repository gets layer 0
+and the forensic tier, and little else of value.
+
+## Files
+
+| File                     | Contents                                                               |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `guidance/catalog.md`    | The rules nothing else can enforce. Injected every turn                 |
+| `guidance/review.md`     | The judgment layer: triage, catalog, false positives, de-slop workflow |
+| `rules.ts`               | Loads and caches the catalog and the review guide                      |
+| `guide.ts`               | Serves `guidance/review.md` through the `timbre_review_guide` tool     |
+| `patterns.ts`            | Every mechanically detectable tell, as data. Detection only            |
+| `scan.ts`                | Layer 1 prose. Pure functions, no I/O                                  |
+| `stats.ts`               | Layer 2. Burstiness                                                    |
+| `register.ts`            | Path to register classification                                        |
+| `prevent.ts`             | Layer 0. Composes the block and the recurring-tells line               |
+| `memory.ts`              | Layer 4. Per-project state and the effect calculation                  |
+| `report.ts`              | Formatting for the model and for the terminal                          |
+| `index.ts`               | Event wiring                                                           |
+
+## Development
+
+From the repo root:
+
+```sh
+just test timbre/
+just check
+```
+
+`just check` runs the typecheck, plain Oxlint, the repo anti-slop pass, and
+the full test suite, all from `extensions/`, which is where `tsconfig.json` and
+`node_modules` actually live. Running `tsc`/`oxlint` directly from any other directory
+finds neither. The anti-slop pass stays scoped to `timbre/` rather than the whole package:
+turning it on repo-wide would also fail against node_modules and pre-existing files this
+extension never touched.

package/src/code.ts

@@ -0,0 +1,154 @@
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { promisify } from 'node:util'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { ToolResultEvent } from '@earendil-works/pi-coding-agent'
+import type { Hit } from './scan.js'
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+function findOxlintBin(): string {
+    let dir = HERE
+    while (true) {
+        const candidate = join(dir, 'node_modules', '.bin', 'oxlint')
+        if (existsSync(candidate)) return candidate
+        const parent = dirname(dir)
+        if (parent === dir) return join(HERE, '..', '..', 'node_modules', '.bin', 'oxlint')
+        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 TS_FILE = /\.(ts|tsx|js|jsx|mjs|cjs)$/i
+const SKIP_CODE = [
+    /\.d\.(ts|mts|cts)$/i,
+    /\.min\.(ts|tsx|js|jsx|mjs|cjs|css)$/i,
+    /\.snap$/i,
+    /\.gen\.(ts|tsx|js|jsx)$/i,
+    /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb)$/i
+]
+const TIMEOUT_MS = 10_000
+const PREFIX = 'anti-slop('
+
+const execFileAsync = promisify(execFile)
+
+type OxlintDiagnostic = {
+    code: string
+    filename?: string
+    message?: string
+    labels?: Array<{ span?: { line?: number } }>
+}
+
+const OxlintReportSchema = t.object({ diagnostics: t.optional(t.unknown()) })
+const isOxlintReportSchema = new Validator(OxlintReportSchema).isValidObject
+const OxlintDiagnosticSchema = t.object({
+    code: t.string(),
+    filename: t.optional(t.string()),
+    message: t.optional(t.string()),
+    labels: t.optional(
+        t.array(
+            t.object({
+                span: t.optional(t.object({ line: t.optional(t.number()) }))
+            })
+        )
+    )
+})
+const isOxlintDiagnosticSchema = new Validator(OxlintDiagnosticSchema).isValidObject
+
+export function codePath(
+    event: Pick<ToolResultEvent, 'toolName' | 'input'>,
+    cwd: string,
+    isError = false
+): string | null {
+    if (isError) return null
+    if (event.toolName !== 'write' && event.toolName !== 'edit') return null
+    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 (SKIP_CODE.some((re) => re.test(abs))) return null
+    return abs
+}
+
+export type CodeFinding = Hit & { path: string }
+
+/**
+ * One oxlint process for the whole turn.
+ *
+ * The spawn is ~130ms of fixed cost and the marginal file is 2-3ms: forty files
+ * measured 230ms against 135ms for one. So the check runs once per turn over
+ * every code file the turn touched, off the write's critical path, rather than
+ * once per write where the fixed cost was paid N times for nothing.
+ */
+// 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 {
+    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
+}
+
+export async function scanCodeBatch(
+    paths: string[],
+    bin = OXLINT_BIN,
+    config = OXLINT_CONFIG
+): Promise<CodeFinding[] | null> {
+    const unique = [...new Set(paths)].filter((path) => existsSync(path))
+    if (unique.length === 0) return []
+    try {
+        const { stdout } = await execFileAsync(bin, ['--config', config, '--format', 'json', ...unique], {
+            encoding: 'utf-8',
+            timeout: TIMEOUT_MS,
+            maxBuffer: 32 * 1024 * 1024
+        })
+        return parseOxlint(stdout)
+    } catch (err) {
+        // absent for a spawn failure, so the field is optional.
+        return parseOxlint((err as { stdout?: string }).stdout ?? '')
+    }
+}
+
+export function parseOxlint(stdout: string): CodeFinding[] | null {
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(stdout)
+    } catch {
+        return null
+    }
+    if (!isOxlintReportSchema(parsed)) return null
+    const report = parsed
+    // A report whose diagnostics field is present but not a list is malformed, and
+    // reading it as an empty list would report a broken spawn as a clean file.
+    if (report.diagnostics !== undefined && !Array.isArray(report.diagnostics)) return null
+    const diagnostics = report.diagnostics ?? []
+    const seen = new Set<string>()
+    const out: CodeFinding[] = []
+    for (const d of diagnostics) {
+        if (!isAntiSlop(d)) continue
+        const line = d.labels?.[0]?.span?.line ?? 0
+        const path = d.filename ?? ''
+        const key = `${path}:${d.code}:${line}`
+        if (seen.has(key)) continue
+        seen.add(key)
+        out.push({
+            path,
+            line,
+            id: d.code.slice(PREFIX.length, -1),
+            tier: 1 as const,
+            hint: d.message ?? '',
+            text: ''
+        })
+    }
+    return out
+}
+
+function isAntiSlop(d: unknown): d is OxlintDiagnostic {
+    if (!isOxlintDiagnosticSchema(d)) return false
+    return d.code.startsWith(PREFIX)
+}

package/src/config.ts

@@ -0,0 +1,21 @@
+export type Config = {
+    enabled: boolean
+    prevent: boolean
+    watchChat: boolean
+}
+
+const FALSE = /^(0|false|no|off)$/i
+
+function flag(name: string, fallback: boolean): boolean {
+    const raw = process.env[name]
+    if (raw === undefined || raw === '') return fallback
+    return !FALSE.test(raw)
+}
+
+export function loadConfig(): Config {
+    return {
+        enabled: flag('TIMBRE', true),
+        prevent: flag('TIMBRE_PREVENT', true),
+        watchChat: flag('TIMBRE_WATCH_CHAT', true)
+    }
+}

package/src/guidance/catalog.md

@@ -0,0 +1,17 @@
+<!-- lint-disable -- this file names the tells it forbids -->
+
+# Writing constraints
+
+## Never
+
+Em or en dashes, or a double hyphen as one. A semicolon joining two clauses, split the
+sentence. A typographic ellipsis. Title Case Headings, use sentence case. "utilize" or
+"leverage" for "use". Throat-clearing ("it's worth noting", "here's the thing"). Announcing
+what comes next ("let's dive in"). An opening hook ("Ever wondered", "In today's
+fast-paced world"). A summary or upbeat closing line. A self-answered beat ("The result?").
+"not X, it's Y".
+
+Code: comment only a non-obvious invariant, a security reason, or a contract. No debug
+logs, commented-out code, scaffolding, test ceremony where a plain test is clearer, or
+adapter layers the neighbouring code does without. The malformed-input cases that survive
+belong at real trust boundaries. The gate lint enforces these on every check.