ytdb-slate 0.5.1 → 0.6.0

package/README.md

@@ -1,5 +1,7 @@
 # ytdb-slate
 
+[![CI status](https://github.com/JetBrains/ytdb-slate/actions/workflows/tier-1.yml/badge.svg?branch=main)](https://github.com/JetBrains/ytdb-slate/actions/workflows/tier-1.yml)
+
 Slate is a thread-weaving orchestration extension for the [pi coding agent](https://pi.dev).
 
 The orchestrator (your main pi session) dispatches **bounded actions** to persistent **worker threads**. Each completed action is compressed by an LLM into an **episode** — a durable, structured record (intent, actions, findings, artifacts, open issues, handoff notes) that the orchestrator composes into further dispatches instead of re-reading raw transcripts. On top of that, Slate injects a mandatory workflow doctrine: research before design, design review, adversarial review, and track review — with optional umbrella **draft-PR publishing** for tracks. An opt-in **model-failover** map adds high availability: when a model API fails, the orchestrator, worker threads, and episode compression each retry once on a configured equal-quality alternative. A second opt-in, **action-level model routing**, gives each dispatched action a model and an effort level chosen to be up to the task and no more, so cost is bounded per action instead of per session.
@@ -57,6 +59,16 @@ Slate can pick the model and the effort level per dispatched action rather than
 
 What the code enforces is deliberately narrower than what the routing data advises. The dispatch guards refuse an unlisted model, a level off the target model's ladder and a level the provider rejects outright; they warn about — and mark — an unmeasured level, refusing it only when `router.allowUnmeasuredEffort` is `false`; and the context-window guard substitutes a wider listed model instead of ever blocking an action. The obligations that come from the profile data itself — keeping review and gate actions on measured levels, and honoring a REFUSE such as `anthropic/claude-fable-5`'s for zero-data-retention work — are stated in the doctrine for the orchestrator to honor; they are **not** code-enforced guards. Full semantics: the `router.*` rows in [Configuration](#configuration) and the shipped [`docs/model-routing.md`](docs/model-routing.md) — if they disagree, that document wins.
 
+## Optional writing guidance
+
+Set `writing.check` to `true` to add writing guidance and human-only telemetry. In orchestrator mode, Slate adds a doctrine rule that states the convention. It also adds a status value such as `writing 1/4`. This value means that one of four measured prose turns had a fail-level finding. Each worker gets a shorter preamble reminder about sentence length, semicolons, and contractions.
+
+The option has prompt cost. Each orchestrator system prompt contains the doctrine rule. You pay for this text on every turn. Each worker session also gets a gated preamble addition. Both additions are absent when the option is off. The worker preamble then stays byte-identical to its pre-feature form.
+
+> **No conformance claim:** This is a dictionary-free proxy. It embeds no controlled vocabulary and claims no ASD-STE100 conformance.
+
+The shipped CLI checks plain files, JSONL records, and unified diffs. See [`docs/writing-guidance.md`](docs/writing-guidance.md) for its rules, limits, output, and command examples.
+
 ## Install
 
 Install into a project (pinned, project-scoped — recorded in `.pi/settings.json`):
@@ -82,6 +94,7 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | `orchestratorPromptDocs` | string[] | `[]` | Project markdown files (paths relative to the project root) whose **contents** are appended to the orchestrator system prompt. |
 | `workerPromptDocs` | string[] | `[]` | Project markdown files whose **contents** are appended to every worker-thread system prompt. |
 | `workflow.draftPRs` | boolean | `false` | Enable umbrella draft-PR publishing for tracks. |
+| `writing.check` | boolean | `false` | Add the writing doctrine rule, per-turn status, and worker guidance. An absent option is silently off. A malformed `writing` value, or a non-boolean `check` value, warns and defaults to off. Unknown `writing` keys warn and are ignored. See [`docs/writing-guidance.md`](docs/writing-guidance.md). |
 | `doctrineExtraPath` | string | — | Project markdown whose **content** is appended to the orchestrator doctrine (project-specific workflow additions). |
 | `reviewPerspectivesPath` | string | — | Project review charters, each declaring its own finding-ID prefix. The doctrine references this **path**; the orchestrator reads the file alongside the shipped review rules. |
 | `modelFailover` | object (string → string) | — (empty, failover off) | Map of `provider/id` → equal-quality alternative model; on a model API failure the affected site retries once on the mapped model (worker/orchestrator sites only after pi's own retries are exhausted; episode compression has no pi retry loop). Read once at session start — see [`docs/model-failover.md`](docs/model-failover.md). |
@@ -99,6 +112,7 @@ Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point
   "orchestratorPromptDocs": ["docs/agents/orchestrator-guidelines.md"],
   "workerPromptDocs": ["docs/agents/thread-guidelines.md"],
   "workflow": { "draftPRs": true },
+  "writing": { "check": true },
   "doctrineExtraPath": "docs/agents/workflow-additions.md",
   "reviewPerspectivesPath": "docs/agents/review-perspectives.md",
   "modelFailover": { "anthropic/claude-sonnet-5": "openai/gpt-5.2" },
@@ -143,6 +157,7 @@ In orchestrator mode, Slate appends a short **doctrine** (a block of numbered ru
 - `docs/design-principles.md` — Slate's own design rationale
 - `docs/model-failover.md` — the opt-in `modelFailover` map (**reference documentation** — unlike the entries above it is not workflow doctrine and is not cited by the doctrine)
 - `docs/context-budget.md` — the orchestrator `contextBudget`: defaults, per-model overrides, the window clamp, and the pricing rationale (also **reference documentation**, not cited by the doctrine)
+- `docs/writing-guidance.md` — the optional writing convention, `writing.check` behavior, status line, and checker CLI
 - `docs/model-routing.md` — action-level model routing: the two `router` keys, how a model becomes routable, how an omitted effort level resolves, the dispatch guards, and the warnings a first routed session emits. Unlike the two entries above it **is** cited by the doctrine, by absolute path, but only while the routing rule renders — it is the extra embedded path that appears with the rule, the fourth normally and the fifth when `workflow.draftPRs` is also on, which the size arithmetic in `docs/context-budget.md` accounts for. The routable model list itself is never read from this file: the rule renders it live from the session's own resolution, because that set depends on your registry and credentials.
 
 Project-specific additions layer on top — they extend, not replace, the shipped doctrine — via two distinct mechanisms:

package/docs/context-budget.md

@@ -129,69 +129,93 @@ you pay its input tokens every turn.
 
 **Its size depends on where the package is installed.** That is not
 obvious, and it catches anyone who measures: the doctrine cites the
-shipped docs by ABSOLUTE path, so three to five full filesystem
-paths are embedded in the block — three at minimum
+shipped docs by ABSOLUTE path, so three to six full filesystem paths
+are embedded in the block — three at minimum
 (`track-workflow.md`, `review-rules.md`, `design-principles.md`),
 plus `pr-publishing.md` when `workflow.draftPRs` is on, plus
-`model-routing.md` when the routing rule renders. Every additional
-character in the installed `docs/` directory therefore costs 3–5
+`model-routing.md` when the routing rule renders, plus
+`writing-guidance.md` when `writing.check` is on. Every additional
+character in the installed `docs/` directory therefore costs 3–6
 characters of doctrine.
 
-So the figures below are **portable characters**, defined exactly as
-Slate's own automated size check defines them: the block with each
-occurrence of the installed `docs/` DIRECTORY removed, keeping the
-filename. That makes them install-invariant by construction —
-verified by measuring at a 12-character docs path and at this repo's
-58-character one, which give identical portable counts — and it
-makes the arithmetic one multiplication:
+The figures below are **portable characters**, defined exactly as
+Slate's own automated `doctrine-budget` check defines them: the
+block with each occurrence of the installed `docs/` DIRECTORY
+removed, keeping the filename. That makes them install-invariant by
+construction and makes the arithmetic one multiplication:
 
 > rendered characters = portable + (embedded paths × length of your
 > installed `docs/` directory)
 
-Every row below states its full basis, because router state, model
-count and `draftPRs` each move the number:
+`doctrine-budget` in `verification/resolver-checks.mjs` is the
+definition of record for this convention and its enforced bounds.
+This table is a measured snapshot, not a second authority. It uses
+the same real shipped-profile fixture as that check; the six-model
+rows use the six configured models in this repository's documented
+example. Every row states its full basis, because router state,
+model count, `draftPRs`, and `writing.check` each move the number:
 
-| router | models | `draftPRs` | paths | portable | lines | rendered at a 58-char docs dir |
+| router | models | `draftPRs` | `writing.check` | paths | portable | lines |
 | --- | --- | --- | --- | --- | --- | --- |
-| off | — | off | 3 | 1,929 | 38 | 2,103 |
-| off | — | on | 4 | 1,948 | 38 | 2,180 |
-| on | 6 configured | off | 4 | 3,870 | 58 | 4,102 |
-| on | 6 configured | on | 5 | 3,889 | 58 | 4,179 |
-| on | all 9 shipped | off | 4 | 4,448 | 61 | 4,680 |
-| on | all 9 shipped | on | 5 | 4,467 | 61 | 4,757 |
+| off | — | off | off | 3 | 1,929 | 38 |
+| off | — | off | on | 4 | 2,683 | 53 |
+| off | — | on | off | 4 | 1,948 | 38 |
+| off | — | on | on | 5 | 2,702 | 53 |
+| on | 6 configured | off | off | 4 | 3,879 | 58 |
+| on | 6 configured | off | on | 5 | 4,633 | 73 |
+| on | 6 configured | on | off | 5 | 3,898 | 58 |
+| on | 6 configured | on | on | 6 | 4,652 | 73 |
+| on | all 9 shipped | off | off | 4 | 4,434 | 61 |
+| on | all 9 shipped | off | on | 5 | 5,188 | 76 |
+| on | all 9 shipped | on | off | 5 | 4,453 | 61 |
+| on | all 9 shipped | on | on | 6 | 5,207 | 76 |
 
 An untrusted project reads the first row whatever its `slate.json`
-says: no project config is loaded, so neither optional rule renders.
-Line counts do not vary with the install path. Enabling `draftPRs`
-costs 19 portable characters plus one more embedded path.
+says: no project config is loaded, so no optional rule renders. Line
+counts do not vary with the install path. Enabling `draftPRs` costs
+19 portable characters plus one embedded path. Enabling
+`writing.check` costs 754 portable characters, adds 15 lines to the
+whole doctrine, and adds one embedded path; considered alone, the
+writing rule is 754 portable characters / 16 lines because its
+leading newline becomes the separator when appended.
 
 Two parts of the block grow with configuration rather than with the
 path:
 
 - The routing rule is a live table with ONE ROW PER ROUTABLE MODEL,
   so what renders is the models you CONFIGURE — not the nine Slate
-  ships profiles for. It is 1,941 portable characters / 20 lines for
-  six configured models and 2,519 / 23 for all nine. A model ROW
-  costs 154–186 characters; the legend adds a one-off clause per
-  marker it has to explain, so listing the first cheap-tier model
-  costs ~50 characters more than its row (two new clauses). That is
-  why stepping from six to nine averages 193 per model where the
-  first six average 171.
+  ships profiles for. In this snapshot it is 1,950 portable
+  characters and adds 20 doctrine lines for six configured models;
+  for all nine it is 2,505 characters and adds 23 lines. The six
+  model rows are 146–181 characters; all nine are 146–183. The
+  legend adds a one-off clause per marker it has to explain, so
+  growth is not only the sum of new rows.
 - The worker-extension rule grows per whitelisted extension and per
   tool that extension contributes, so it has no fixed size; one
   extension contributing two tools measured 373 portable characters
   / 7 lines.
 
-Against a 256,000-token budget none of this is material — as a rough
-estimate, at 4 characters per token (no tokenizer was run, and the
-table is denser than prose, so treat it as a floor) the whole block
-is ≈480–525 tokens with both optional rules off and ≈970–1,025 with
-six models routed, each range spanning portable to as-rendered-here.
-That is under half a percent of the default budget, though it is
-re-sent on every request rather than paid once. It is listed here
-because it is context Slate itself puts in front of the model on
-every turn, and because it is the number to check before assuming
-the budget's headroom is all conversation.
+Against a 256,000-token budget none of this is material. At four
+characters per token as a rough estimate (no tokenizer was run, and
+the routing table is denser than prose), the portable block ranges
+from about 482 tokens at the baseline to about 1,302 with all nine
+models, `draftPRs`, and writing enabled. That is close to half a
+percent of the default budget at the largest measured configuration,
+though it is re-sent on every request rather than paid once. It is
+listed here because it is context Slate itself puts in front of the
+model on every turn, and because it is the number to check before
+assuming the budget's headroom is all conversation.
+
+### Worker writing preamble
+
+The doctrine table does not include the worker preamble. It belongs
+to each worker session's system prompt, not to the orchestrator's
+per-turn doctrine. The feature-off preamble is 226 bytes. With
+`writing.check` on it is 384 bytes, a 158-byte increase (the
+157-byte guidance plus its separating space). These are UTF-8 byte
+counts; the current text is ASCII, so its character counts happen to
+be identical. This separate figure states the worker-session cost
+without presenting it as orchestrator doctrine.
 
 ## Worker threads: the routing window guard
 

package/docs/model-routing.md

@@ -447,14 +447,13 @@ model's ladder is unreadable.
 - **In the orchestrator's own system prompt, every turn:** the
   doctrine gains a routing rule — a table with one row per routable
   model, plus the rules for reading it. This is the surface you do
-  not see, and it is the router's standing cost: 1,941 characters /
-  20 lines for six configured models, 2,519 / 23 for all nine — a
-  model row costs 154–186 characters, plus a one-off legend clause
-  for each marker it introduces (listing the first cheap-tier model
-  costs ~50 characters beyond its row, which is why six→nine
-  averages 193 per model against the first six's 171). Configuring
-  the router roughly doubles Slate's always-loaded block (1,929
-  characters with routing off). Those are PORTABLE characters — the
+  not see, and it is the router's standing cost: 1,950 characters /
+  20 added doctrine lines for six configured models, 2,505 / 23 for
+  all nine. In the current snapshot a model row costs 146–183
+  characters, plus a one-off legend clause for each marker it
+  introduces. Configuring the router roughly doubles Slate's
+  always-loaded block (1,929 characters with routing and writing
+  off). Those are PORTABLE characters — the
   doctrine with each occurrence of the installed `docs/` directory
   removed, filenames kept — because the doctrine embeds absolute doc
   paths and its raw size therefore depends on where the package is

package/docs/review-rules.md

@@ -37,14 +37,45 @@ automatically).
 
 ## 3. Choose perspectives by what the change touches
 
-There is no fixed roster — compose perspectives per change. Each
-bullet below is that perspective's charter:
+There is no fixed roster — compose perspectives per change. Every
+perspective has this first step before its specific charter: run
+`node /path/to/slate/extension/writing-check.mjs --diff PATH --format text`
+over the review diff, using the package root that contains this document.
+Report fail-level matches in changed prose governed by the reviewed
+project's writing convention. Diff mode deliberately selects only prose
+file types; inspect user-facing strings and comments in source files
+directly. For this package, [writing-guidance.md](writing-guidance.md)
+defines the convention, its scope and its exclusions.
+
+The checker is diagnostic, not authoritative. It embeds no controlled
+vocabulary and establishes no ASD-STE100 conformance. A clean run does
+not prove that writing is good, and a match is not automatically a
+defect. Apply the project's convention scope before grading output:
+
+- `fail`: in convention-governed changed text, normally `should-fix`;
+  use `blocker` only when the underlying defect prevents safe or correct
+  delivery. In excluded text, it is advisory only.
+- `warning`: normally at most a `suggestion`; raise it only when
+  independent evidence establishes a more consequential defect.
+- `house-style`: at most a `suggestion` when the applicable convention
+  calls for the change; otherwise report nothing.
+- `advisory`: never a defect by itself. File a finding only when
+  independent review establishes an underlying defect, graded on its
+  own consequences.
+
+Reviewer judgment governs every class. The checker cannot decide
+meaning, factual accuracy, claim truth, document structure, topic unity,
+or instruction completeness; those usually matter more than a
+mechanical match. Each bullet below is the remainder of that
+perspective's charter:
 
 - **Code baseline** (any production/test code change): correctness &
   bugs (logic, null safety, resource leaks, lifecycle); code quality
   (readability, duplication, error handling); test quality (do tests
   verify behavior, cover the change, and would they fail on
-  regression?).
+  regression?). Verify documentation claims about the code under review
+  against the implementation already being read. A contradiction is a
+  code-baseline finding, not work to leave for a prose specialist.
 - **Specialists**, added when the change touches their domain:
   - concurrency — any defect requiring reasoning about thread
     interleavings (locks, shared state, atomicity);
@@ -60,14 +91,26 @@ bullet below is that perspective's charter:
   domain specialists). Each charter in that file MUST declare its own
   stable finding-ID prefix (uniqueness rules in §4). Compose them per
   change exactly like the built-in perspectives above.
-- **Non-code artifacts** (docs, prompts, process rules, extension
-  guidance like this file) get their own perspectives INSTEAD of the
-  code baseline: internal consistency & cross-references; instruction
-  completeness (can a reader execute this without guessing?); context
-  budget (what becomes always-loaded vs on-demand); writing style;
-  and safety of any scripts/hooks/config touched.
-- **Mixed diffs**: scope each reviewer to its in-scope files. Code
-  reviewers never review process/docs files, and vice versa.
+- **Non-code baseline** (docs, prompts, process rules, extension
+  guidance like this file): internal consistency & cross-references;
+  factual and instruction completeness (can a reader execute this
+  without guessing?); context budget (what becomes always-loaded vs
+  on-demand); and safety of any scripts/hooks/config touched. This
+  baseline applies instead of the code baseline unless a mixed diff
+  also changes code.
+- **Text specialist**, added when a change ships user-facing or
+  licensing-adjacent prose: licensing and provenance exposure;
+  coherence with the project's writing convention; proportionality and
+  duplication; register, audience fit, structure, and accuracy as
+  prose. User documentation, command help, release notes, prompts, and
+  public-facing messages normally trigger it. Do not dispatch it solely
+  for a short internal code comment, test name, fixture string, or
+  mechanical label unless the text is licensing-adjacent or its prose
+  risk independently warrants review.
+- **Mixed diffs**: scope each reviewer to its charter. Code reviewers own
+  claims that describe their in-scope code even when those claims live
+  in documentation. They do not take on the rest of the non-code or text
+  charter, and non-code reviewers do not take on code correctness.
 - Selection is a judgment call, not a rigid filter — when in doubt,
   include the perspective. Risk/complexity changes how deep iteration
   goes (§6), never which perspectives run.
@@ -156,13 +199,19 @@ review dispatch:
   library code instead of assuming its semantics.
 - Enumerate cases exhaustively along the changed execution paths
   (branches, error paths, boundary values); mark each case as checked
-  or explicitly out of scope.
+  or explicitly out of scope. For prose, enumerate the affected
+  audiences, reader tasks, claims, definitions, cross-references,
+  examples, exceptions, and boundary conditions instead of execution
+  paths.
 - Back every defect claim (blocker or should-fix) with a concrete
   counterexample: the input, state, or interleaving that triggers the
   defect, traced through the code.
 - Back every correctness claim ("no issue here") with a justification
   for why no counterexample exists — not merely the absence of one
-  found.
+  found. For prose, proof of absence means a bounded, reproducible check
+  of the relevant set. Examples include checker output, targeted
+  searches, re-resolved references, and comparison with authoritative
+  sources. State explicitly what those checks cannot establish.
 - Before finalizing, run an alternative-hypothesis check: "if the
   opposite verdict were true, what evidence would exist?" — then look
   for that evidence.
@@ -170,3 +219,7 @@ review dispatch:
   sought → confirmed / refuted / refined) instead of wandering.
 - Derive the final verdict explicitly from the stated definitions and
   claims, not from overall impression.
+- Treat a fix series as a changed artifact that needs review. Verify the
+  addressed finding, then review the fix diff and the cumulative result
+  for new paths, claims, and regressions. Clearing the original finding
+  does not clear defects introduced by its fix.

package/docs/writing-guidance.md

@@ -0,0 +1,322 @@
+# Writing guidance and the prose checker
+
+Slate ships one writing convention and one command that measures
+prose against a mechanical proxy for it. Both are opt-in: with
+`writing.check` absent or false nothing about them is loaded,
+rendered or paid for.
+
+This document is reference documentation, not workflow doctrine. It
+is the definition of record for the rule set, the severity classes,
+the command line and the caps. The always-loaded doctrine rule states
+the convention in a few lines and cites this file for everything
+else, so that a session pays for the detail only when it reads it.
+
+## What the checker is, and what it is not
+
+`extension/writing-check.mjs` is a dependency-free Node command. It
+reads text, strips the parts that are not prose, splits what remains
+into blocks and sentences, and reports surface facts about them:
+sentence length, sentence count per paragraph, and matches for a
+closed list of twelve patterns. It emits per-rule counts, length
+distributions and one finding record per match, each with a source
+offset and a framed excerpt.
+
+**It is a proxy, and the proxy is dictionary-free.** It embeds no
+controlled vocabulary and consults none. It therefore cannot decide
+whether a word is approved, whether a word is used in an approved
+sense or part of speech, or whether a technical term is legitimate.
+It reports those limits in its own output, under `NOT CHECKED` — see
+[What the checker declares unchecked](#what-the-checker-declares-unchecked).
+
+**It establishes no conformance with any writing standard.** ASD-STE100
+inspired the choice of what to measure. Slate claims no conformance
+with it. No text, example or dictionary entry from the standard is
+reproduced here or in the checker. TechScribe's
+[public analysis](https://www.simplified-english.co.uk/analysis.html#write-short-sentences)
+is the source for the 20- and 25-word figures. Boeing's
+[public checker page](https://www.boeing.com/company/simplified-english-checker)
+also publishes that pair and is the source for the six-sentence figure.
+The source repository keeps the citation trail in its non-published
+`research/writing-threshold-provenance.md`. Slate defines the severity
+classes, patterns and suppression lists, and applies one band uniformly
+to all prose rather than selecting a limit by text type. A clean run
+is evidence about surface form only. It is not a certificate.
+
+**It is not an authority over a reviewer.** A match is a place to
+look, not a verdict. `review-rules.md` governs how a text reviewer
+turns checker output into findings and severities, and it is the
+document to follow when reviewing prose. The short version: a
+`fail` class match deserves inspection, an `advisory` class match is
+never a defect on its own, and the checker cannot see meaning,
+accuracy, structure or completeness at all.
+
+## Enabling it
+
+One boolean in the project's `.pi/slate.json`:
+
+```json
+{ "writing": { "check": true } }
+```
+
+The default is false. An absent `writing` key is silent. A malformed
+one warns once and leaves the feature off, as does a non-boolean
+`check`; unknown keys under `writing` warn and are ignored. The
+validator is `sanitizeWritingConfig` in `extension/writing.ts`.
+
+Slate reads project config only for a TRUSTED project. Both
+prompt-visible sites also re-check trust when they inject the doctrine
+rule or worker preamble. The worker check is defense in depth for a
+future direct call to `openWorkerSession`; the current config path is
+already gated in `extension/index.ts`. An untrusted project therefore
+behaves as if the switch were off, whatever its `slate.json` says.
+
+The switch turns on three things and nothing else:
+
+1. **The doctrine rule.** One numbered rule is appended to the
+   orchestrator's system prompt while orchestrator mode is on. It
+   states the convention and cites this file by absolute path.
+2. **The worker preamble sentence.** Every worker thread dispatched
+   while the switch is on gets one extra sentence of guidance in its
+   preamble. With the switch off the preamble is byte-identical to
+   its pre-feature text.
+3. **The turn status line.** In an interactive session, the Slate
+   status line gains a `writing <n>/<m>` counter: `m` turns of the
+   orchestrator's own prose were measured and `n` of them carried at
+   least one `fail` class match.
+
+Running the command by hand needs no config at all. It is a plain
+Node command and it works whether or not the switch is on.
+
+## What it costs when it is on
+
+The doctrine rule is part of every orchestrator system prompt, so its
+cost is paid on every turn. The worker addition is paid once per
+worker dispatch. `context-budget.md` defines the portable-character
+measure, records the whole-doctrine sizes and owns the size budget.
+
+An interactive session also runs the checker synchronously after each
+completed assistant message. The hook refuses text over 16 KiB and
+reports `writing skipped (message too large)`. This TUI bound is
+separate from the command's 1 MiB input cap. The hook is human-only
+telemetry: it does not change the model input, and a checker failure
+reports `writing unavailable` rather than failing the turn.
+
+## What counts as prose
+
+Rules run over blocks, and only some blocks are prose. Before any
+block is formed, the normalizer BLANKS the spans that are not prose,
+keeping the source length so that every reported offset still points
+into the original text:
+
+- fenced code blocks, including an unterminated final fence;
+- indented code (four or more leading spaces followed by a character
+  that is not a list marker);
+- unified-diff lines (`diff --git`, `@@`, `---`, `+++`);
+- timestamped log lines (an ISO-8601 timestamp followed by a level
+  such as `INFO` or `ERROR`);
+- HTML comments;
+- inline code spans;
+- autolinks (`<https://…>`, `<mailto:…>`) and bare URLs.
+
+What remains is split into lines and classified: `table-row`,
+`heading`, `blockquote`, `list-item` or `paragraph`. Consecutive
+paragraph lines join into one block with a single space, so a sentence
+wrapped across source lines is one sentence. The block keeps a map
+from its joined text back to source offsets, so findings on a
+multi-line paragraph report the right characters.
+
+Rules and prose statistics apply to `paragraph`, `list-item` and
+`blockquote` blocks. Headings and table rows are parsed and counted as
+blocks, but no rule fires in them and they contribute no words or
+sentences to the statistics. `PARA6` is narrower still: it applies to
+`paragraph` blocks only.
+
+Sentences are split at `.`, `!` or `?` when followed by whitespace or
+the end of the text. A period is treated as internal, and does not
+split, when it is doubled, sits between two digits, ends one of a
+small fixed abbreviation list (`e.g.`, `i.e.`, `etc.`, `vs.`, `dr.`,
+`mr.`, `mrs.`, `ms.`, `prof.`, `sr.`, `jr.`, `no.`, `fig.`,
+`approx.`, `dept.`, `inc.`, `ltd.`, `st.`), or closes an initialism
+such as `U.S.`. An ellipsis is one punctuation run, not three empty
+sentences. A candidate sentence with no letter in it is dropped.
+
+A word is a run of letters and digits, with internal apostrophes and
+hyphens kept, that contains at least one letter. So a hyphenated
+compound counts as one word and a bare number counts as none.
+
+Four of the twelve rules ignore identifier-shaped text. `PASSIVE`,
+`INGFORM`, `NOUNCLUSTER` and `MULTICMD` run over a filtered token
+list with path-like tokens, dotted names, `snake_case`, `camelCase`
+and em-dash-bearing quotations removed, so a file name or a symbol
+cannot trip them. The length, punctuation and parenthetical rules see
+the unfiltered text.
+
+## The rules
+
+Twelve rules in four severity classes. The class is the checker's own
+label, reported with every finding and in the per-rule summary.
+
+**`fail` — a mechanical violation of the convention.**
+
+| rule | what it flags |
+| --- | --- |
+| `SENT25` | a sentence of more than 25 words |
+| `PARA6` | a paragraph block of more than 6 sentences |
+| `SEMICOLON` | each `;` in a prose block |
+| `CONTRACTION` | a contracted form. Two shapes match: a pronoun or one of `that`, `there`, `here`, `what`, `who`, `how`, `where`, `when`, `why`, `let` carrying `n't` or `'re`, `'ll`, `'ve`, `'d`, `'m`, `'s`; and a negated auxiliary such as `don't`, `won't` or `shan't`. Straight and curly apostrophes both match |
+
+**`warning` — over the comfortable length, under the failing one.**
+
+| rule | what it flags |
+| --- | --- |
+| `SENT20` | a sentence of more than 20 words and at most 25 |
+
+A sentence reports one length result at most: `SENT25` when it is
+over 25 words, `SENT20` when it is over 20, and nothing otherwise.
+
+**`house-style` — legitimate constructions this convention avoids.**
+
+| rule | what it flags |
+| --- | --- |
+| `PARENTHETICAL_PAREN` | a parenthesis pair whose content looks like a clause rather than an aside. The test is a surface one: an auxiliary or `be` form, a word ending in `ed` or `es`, or a non-initial word ending in `s` |
+| `PARENTHETICAL_DASH` | a paired em dash, or a spaced en dash pair, enclosing text. A pair inside a quotation that itself contains an em dash is suppressed |
+| `SLASHED` | a letters-only `word/word` construction such as `and/or`. Paths and URLs are already blanked, and a longer slash run does not match |
+
+**`advisory` — noisy heuristics, never a defect on their own.**
+
+| rule | what it flags |
+| --- | --- |
+| `PASSIVE` | a `be` form, optionally followed by an `-ly` adverb, then a likely participle: a word ending in `ed`, or one of a fixed irregular-participle list. A fixed list of state-like participles (`connected`, `installed`, `configured` and others) is suppressed, which lowers noise and can hide a real passive |
+| `INGFORM` | a word ending in `ing` that is not preceded by a `be` form. A first token of a multi-token sentence is skipped, deliberately, because it is usually a gerund subject or a heading-like phrase |
+| `NOUNCLUSTER` | a run of four or more words with no function word between them |
+| `MULTICMD` | a token shape: a sentence starts with a non-function word and later has `and`, `and then` or `, then` followed by another non-function word. It approximates multiple commands but can match ordinary coordination such as “Files and folders exist.” |
+
+Only the `fail` class moves the turn status counter. A `warning`,
+`house-style` or `advisory` match is reported and counted, but the
+counter treats the turn as clean.
+
+Two properties are worth knowing before reading a report. Rule ids
+and classes come from one closed table in the module, so a report can
+never name a rule the table does not define. Every finding carries a
+source offset range, a block index, a sentence index where the rule
+is sentence-scoped, and an excerpt framed in `⟦…⟧` with the framing
+characters removed from the content, so the frame is always the
+checker's and never the text's.
+
+## The command line
+
+```
+node extension/writing-check.mjs --input records.jsonl [--format json|text]
+node extension/writing-check.mjs --file PATH [--file PATH ...] [--format json|text]
+node extension/writing-check.mjs --diff changes.diff [--format json|text]
+```
+
+Exactly one input mode per run. `--format` is `json` by default and
+`text` for a human-readable report. `--help` prints the usage.
+`--input` and `--diff` take one path each; `--file` repeats.
+
+Every input must be a REGULAR FILE. The command refuses a symlink, a
+directory, a FIFO or a device. It checks the opened descriptor and
+rejects a special file substituted between the initial check and the
+open. It also detects growth while reading. It does not detect every
+race or a same-size in-place modification.
+
+### `--input`: JSONL records
+
+One JSON object per line, each with a string `text` field. A missing
+or non-string field is rejected. `id` names the record in the report;
+with no `id` the record is named from its `session` and `line` fields,
+else from its position. Blank lines are skipped. This is the mode for
+text that is not a file on disk — an extracted message, a comment
+body, a release note draft.
+
+### `--file`: whole files
+
+One record per path, named by the path. This is the mode for a
+complete prose artifact: a document, a README, a release note.
+
+### `--diff`: added lines of a unified diff
+
+Reads a unified diff and checks the ADDED lines only. Consecutive
+added lines form one record, named `path:firstAddedLine`, so a
+sentence added across several lines is checked as one sentence. It
+parses hunk headers strictly and fails loudly on a malformed diff
+rather than checking a mis-attributed line.
+
+Diff mode is for PROSE review, and its file filter is deliberately
+narrow. It includes `.md`, `.markdown`, `.mdx`, `.txt`, `.rst`,
+`.adoc` and `.asciidoc`, plus a small closed set of extensionless
+conventional names (`readme`, `changelog`, `changes`, `contributing`,
+`release_notes`).
+
+It therefore EXCLUDES source files entirely, and that exclusion is
+the mode's main limitation: prose that lives inside code — a
+user-facing string, a comment, a help text, a commit message — is not
+reviewed by `--diff`. Inspect those directly, or extract the text and
+pass it through `--input`. Git's quoted-path encoding is decoded
+before a path is classified or reported; a path that is not valid
+UTF-8 is skipped and named in a `DIFF FILES SKIPPED` line rather than
+being checked under a false name.
+
+### Caps
+
+Every cap is a hard bound with a reported consequence, never a silent
+truncation.
+
+| cap | value | applies to |
+| --- | --- | --- |
+| input bytes | 1,048,576 | one record, and the total across a run's records or files |
+| records | 10,000 | a JSONL input, a `--file` list, and a diff's added-line runs |
+| findings per record | 1,000 | one record's reported findings |
+| findings per run | 20,000 | the whole run, shared as an EQUAL per-record allowance |
+| excerpt characters | 2,000 | one finding's excerpt, framing characters included |
+| reported stripped spans | 5,000 | the reported non-prose span list |
+| reported block details | 5,000 | the reported per-block detail list |
+
+The per-run budget is divided equally rather than first-come, so a
+record's position never decides what it keeps, and the floor is one
+finding per record so that a large run still shows every offending
+record. When the run budget binds, the report states it BEFORE any
+finding line, so a reduced report cannot read as a complete one. A
+record that loses findings reports its own shortfall. The two
+5,000-span caps bound the REPORT only: blanking and counting are
+always complete.
+
+## What the checker declares unchecked
+
+The report ends with a `NOT CHECKED` list. It is part of the output on
+purpose: the limits are a result, not a footnote.
+
+| id | why not |
+| --- | --- |
+| `APPROVED_WORD` | approved-word membership needs an authorized controlled dictionary |
+| `APPROVED_MEANING_POS` | approved meaning and part of speech need authorized dictionary data and contextual review |
+| `NOUNCLUSTER_CORRECTNESS` | the token-run heuristic cannot decide whether a noun cluster is wrong or is an approved technical term |
+| `TOPIC_UNITY` | topic unity and topic-sentence adequacy need semantic review |
+| `WARNING_CAUTION_CONTENT` | risk level, placement, command adequacy and consequences need structured metadata and human review |
+
+## What this feature deliberately does not do
+
+These are settled decisions. Read them as scope, not as a backlog.
+
+- **No controlled vocabulary, and no plan for one.** Word approval
+  needs an authorized dictionary. Slate ships none and embeds none.
+- **No conformance claim.** ASD-STE100 inspires the choice of what to
+  measure. Slate claims no conformance. No text, example or dictionary
+  entry from the standard is reproduced here or in the code.
+- **No vocabulary or terminology enforcement.** The convention keeps
+  exact technical terms, so the checker must not push a writer off
+  them. Nothing in it rewrites, replaces or grades a word choice.
+- **No broad prose rewriting.** The checker reports and never edits.
+  Every fix is a human or agent decision.
+- **No verdict.** No rule class is a defect by itself, and no clean
+  run is a pass. `review-rules.md` owns the mapping from a match to a
+  severity, and a reviewer owns the judgement.
+- **Not a gate.** The turn hook is telemetry. It returns nothing to
+  the model, changes no prompt, and cannot fail a turn.
+- **Not universal.** The convention covers prose written for people:
+  documents, README text, pull request and commit text, issues,
+  review comments, release notes and messages to the user. Research
+  logs, worker task text and this repository's own agent instruction
+  file are excluded, because a dense exact register serves them
+  better.