clearotron 0.3.1 → 0.3.2-beta.0

package/CONTRIBUTING.md

@@ -93,7 +93,7 @@ served to the model at run time — `synthesis-rules.md` is a 16,000-word progra
 brevity, tone or tidiness changes what a clearance concludes. Nothing in this section, and nothing in
 any writing pass over the documentation, applies to them.
 
-## The three rules that fail CI
+## The four rules that fail CI
 
 **1. Build `portal-ui/dist` before you push.** The bundle is not committed; it is gitignored, and
 CI runs `npm run build:ui` from source. So there is nothing to add — run it locally when you touch
@@ -130,6 +130,35 @@ The reviewer is the check. Say what you checked in the PR rather than citing a p
 **3. Types are enforced, and `vite build` does not typecheck.** `npm run typecheck -w portal-ui`
 runs as its own CI step. Run it before you push.
 
+**4. Every sentence a customer reads is written against the standard, and five classes of it are
+checked.** The standard is [`docs/writing-standard.md`](docs/writing-standard.md); the prose rules
+under it are [`docs/writing-rules.md`](docs/writing-rules.md), and they apply first. Together they
+bind report HTML, portal screens, the README and the docs.
+
+`node scripts/writing-standard-check.mjs` refuses what your change ADDS to one of those surfaces:
+an engineering identifier in text a client reads, a reviewer-only marker in rendered output, a known
+caveat sentence, a screen that writes its own page heading instead of using `PageHeader`, and a lede
+whose words are all already in its title. It names the class and prints the line. It never rewrites —
+a rewritten sentence is a sentence nobody reviewed.
+
+It refuses what you add, not what is already here. The standing population is counted per file and
+per class in `driver/test/fixtures/writing-standard-backlog.json`, and the floor beside it refuses
+any file that grows, so the number can only fall. If you repair one, re-mint the floor with
+`node scripts/mint-writing-standard-backlog.mjs --apply` so it drops with the tree.
+
+### The review step, for what no check can judge
+
+Tone is not one of the five classes and no word list will ever catch it. A sentence can carry no
+identifier, no caveat and no banned word and still be the thing the standard exists to stop: a
+heading that restates its section, a paragraph explaining what the reader can already see, a sentence
+that only works if you know how the engine is built.
+
+So: **a pull request that changes text a customer reads is reviewed against the rendered page or
+report, not against the diff.** One reviewer reads it as someone who has never seen this product and
+asks one question of every new sentence — *what would a reader with zero context think this means?*
+If the answer needs the codebase, the sentence is cut or rewritten. One reviewer, one question,
+recorded in the pull request.
+
 ### If your change touches a Markdown file, two more will catch you
 
 Both are in `npm run test:full` rather than the fast tier, and neither is something a reviewer spots.

package/README.md

@@ -139,6 +139,7 @@ credential.
 | Check it works before spending anything | [docs/E2E.md](docs/E2E.md) |
 | Understand the architecture | [docs/architecture/](docs/architecture/) · [decisions](docs/decisions/) |
 | Run it under your own name, or fork it | [docs/branding.md](docs/branding.md) · [TRADEMARKS.md](TRADEMARKS.md) |
+| Write a sentence a customer will read | [docs/writing-standard.md](docs/writing-standard.md) · [docs/writing-rules.md](docs/writing-rules.md) |
 
 ## Development
 

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "6e95648a34fce4d8d0a73b9359a89925b0af3a36",
-  "version": "0.3.1"
+  "commit": "0bc01b5d6cda940a40dc2fb7da2ae5f83caf3f5b",
+  "version": "0.3.2-beta.0"
 }

package/docs/writing-rules.md

@@ -0,0 +1,208 @@
+# Writing Rules
+
+From the On Style writing rules, https://github.com/gundersen/on-style, MIT licence; reproduced here so the standard is complete on its own. The licence text is at the end of this file.
+
+*Apply these to all prose you produce.*
+
+*These rules fight trained instincts. Pay special attention to: no hedging, no over-explaining, keep it short, no metadiscourse, finish strong, and don't fake contradiction. These are the rules most likely to be violated — enforce them first.*
+
+---
+
+# Words — what to use and what to cut
+
+## Cut dead weight
+
+Every word must earn its place. Kill:
+- **Zombie nouns**: "make an appearance" → "appear"; "provide an explanation" → "explain"
+- **Light verbs** propping up nominalizations: make, do, have, bring, put, take
+- **Metaconcept filler**: matter, view, subject, process, basis, factor, level, model
+- **Throat-clearing openers**: "It is worth noting that...", "It should be pointed out that...", "There is a tendency for..."
+
+If a 40-word sentence says what 15 words can say, use 15.
+
+## Be concrete
+
+Use nouns and verbs, not adjectives and adverbs. Prefer plain words over fancy ones. Replace abstractions with the tangible things they refer to — people, actions, objects. If the reader can't picture it, rewrite it. Be concrete about the argument; be vague about the scenery.
+
+"The company experienced a significant deterioration in operational performance across multiple facilities during the quarter" — how many facilities? What happened? "Three factories missed production targets and the Chicago plant shut down for two weeks" — now the reader sees it.
+
+## No jargon
+
+If a phrase requires a second phrase to explain it, use the explanation. "How the AI in our weapons makes decisions" — not "autonomy governance." "We raised $50M to build bigger rockets" — not "we secured a strategic capital infusion to scale our launch vehicle program." The test: could a smart outsider follow it without a glossary?
+
+## No hedging — make definite assertions
+
+Don't reflexively pad with: almost, apparently, fairly, somewhat, sort of, to a certain degree, relatively, presumably. Cut throat-clearing qualifiers: actually, of course, surely, in fact, just, so, pretty, that said. Hedge only when genuine uncertainty exists and the reader needs to know about it. When you hedge, do it once and with precision — not as a verbal tic.
+
+Beyond avoiding hedges, write with force. A sentence can be hedge-free and still limp. "The project went okay" has no qualifiers but says nothing. "The project shipped three weeks late and lost the client" says something.
+
+## No intensifiers
+
+Drop: very, highly, extremely, incredibly, truly, really, quite. These words weaken rather than strengthen. An unmodified claim reads as categorical and confident. Adding "very" turns it into a score on a scale.
+
+## No GPT-isms
+
+If it sounds like a language model wrote it, rewrite it. Ban list:
+- **Compound modifiers that mean nothing**: "operationally relevant," "institutionally protected," "non-fragmentable," "identity-defining institutional constraint," "mission-critical," "best-in-class"
+- **Faux-precision hedges**: "it's worth noting that," "it's important to understand," "this is particularly significant"
+- **Breathless connectors**: "moreover," "furthermore," "indeed," "notably," "crucially," "importantly"
+- **Vague authority words**: "robust," "comprehensive," "strategic," "leveraging," "ecosystem," "synergy," "paradigm," "holistic"
+- **Performative structure**: "Let's break this down," "Here's the thing," "There are several key factors to consider"
+
+The test: if the phrase exists only because an LLM stitched together impressive-sounding words, cut it.
+
+---
+
+# Sentences — how they move
+
+## Active voice by default
+
+Put the agent before the action. "The board approved the deal" — not "The deal was approved by the board." If you can't name who's doing it, the sentence is hiding. Use passive only when the doer is unknown, unimportant, or when you need to shift emphasis deliberately.
+
+## Light before heavy
+
+Put short, simple phrases before long, complex ones. Topic before comment. Given information before new information. End sentences with the material that deserves the most emphasis.
+
+"The executive team, after weeks of deliberation and consultation with outside counsel regarding the potential regulatory implications, approved the merger." The verb arrives too late. Flip it: "The executive team approved the merger after weeks of deliberation over regulatory risk."
+
+## One idea per sentence
+
+If a sentence tries to do two things, split it. If the reader has to reread it, it's too long or too tangled. The difficulty of a sentence depends on its geometry, not just its word count — avoid deeply nested clauses.
+
+## Punctuation is breath
+
+Punctuation controls how the reader hears you — the pacing, the pauses, the asides. A comma sounds different than a semicolon; parentheses make a different noise than dashes. Read sentences aloud. Where you pause naturally, punctuate. Where the punctuation forces an unnatural pause, remove it.
+
+Two bright-line rules:
+- **Always use the serial comma.** "Guards, dogs, and sensors" — keep the comma before "and." It eliminates ambiguity and costs nothing.
+- **Never use exclamation points.** Let the words carry the emphasis. If the sentence needs a ! to land, the sentence isn't strong enough.
+
+## Don't fake contradiction
+
+Don't toss in a "But" or "However" to create the illusion that a second thought contradicts a first when it doesn't. "However" is not a synonym for "and" or "also" — it signals a turn. If there's no turn, drop it. Use contrastive connectors only when there is an actual contrast.
+
+## Watch for dangling modifiers
+
+"Walking through the data, the trend becomes clear" — the trend isn't walking. Make sure the modifier attaches to the subject of the sentence. "Walking through the data, we noticed a clear trend." If the sentence reads fine but the grammar is wrong, the reader will stumble even if they can't say why.
+
+## Name the thing
+
+Don't open a sentence with "this," "that," "these," or "it" unless the referent is unmistakable from the previous sentence. Vague pronouns break coherence — the reader has to look back to figure out what you mean. When in doubt, name the thing. "This approach" instead of "This." "The deal" instead of "It."
+
+## Consistent terms, consistent vantage
+
+If you use two different words, the reader assumes you mean two different things. Don't vary terminology for variety's sake. Stay in one tense, one voice, one point of view — don't flip without reason.
+
+---
+
+# Paragraphs & Structure — shape and sequence
+
+## Show, don't announce
+
+Lead with the thing itself. Never open with "In this section I will discuss..." or "It's important to note that..." — just say it. No metadiscourse. No narrating your own writing process.
+
+## Connect every sentence
+
+Each sentence must follow from the one before it. Don't dump facts without showing how they relate. Use a logical sequence: general to specific, cause to effect, chronological, or big to small. If adding "therefore," "however," or "for example" between two sentences doesn't make sense, the transition is broken.
+
+## Every paragraph earns its place
+
+Each paragraph should have a single job. Begin with a sentence that states or implies the point. Let the following sentences develop it. End with emphasis, not a digression. A paragraph is a complete thought — not a visual break you insert when the block of text looks too long. If you can't say what a paragraph is about in one sentence, it's doing too many things.
+
+## Finish strong
+
+End paragraphs and sections with the sentence that carries the most weight. Don't trail off with qualifications or filler. The last thing the reader sees is what sticks.
+
+"The deal, which was the largest acquisition in the company's history, closed Tuesday at $4.2 billion after six months of negotiation." The best fact is buried in the middle. Rearrange: "After six months of negotiation, the deal closed at $4.2 billion — the largest acquisition in the company's history."
+
+## Say it once
+
+State a principle in one place. Reference it after that. Never re-derive the same idea from scratch in every section.
+
+## The rule of threes
+
+People remember things better when grouped in threes. Three main points, three examples, three items in a list. It keeps structure clear and memorable. When you have five points, see if two of them are really the same point. When you have seven, you've lost the reader.
+
+## Keep it short
+
+If an email could be 3 sentences, don't write 3 paragraphs. Say it in as few paragraphs as the argument requires. Cut entire paragraphs the same way you cut words — if removing it doesn't hurt the argument, it was never helping.
+
+---
+
+# Calibration — proportions and matching claims
+
+## Respect the reader
+
+Assume the reader is intelligent but doesn't share your specialized knowledge. Explain terms without being condescending. Never write in a way that makes the reader feel stupid — classic style makes the reader feel like a genius.
+
+## Sometimes less detail is more accurate
+
+Don't fabricate specifics to sound authoritative. "The company was founded in the early 2000s" is more accurate than "the company was founded in 2003" if you don't actually know the year. Precision with nonessential details invites errors and adds noise. Be specific when the detail matters and you're confident in it.
+
+## Do not overstate
+
+If you say "revolutionary" and the reader thinks "incremental," you've lost them — not just on that sentence but on everything that follows. Make claims proportional to the evidence. Overstatement erodes trust faster than understatement. Let the facts do the persuading.
+
+## Do not explain too much
+
+State it, show it, move on. If you state a principle and then explain it and then explain the explanation, you're writing a textbook, not a memo. Let examples reveal the point. Trust the reader to follow.
+
+## Numbers over superlatives
+
+If a number could replace a word or phrase, use the number. "Revenue growth significantly outpaced expectations in Q2" — by how much? "Revenue grew 34% in Q2, beating the Street estimate by 11 points" — now the reader can think with it. If a sentence still needs a qualitative descriptor after the number is included, use a calibrated and neutral term ("modest," "material" with a defined threshold) rather than an evocative one.
+
+## No emotionally charged framing
+
+Phrases like "not your salvation," "you're in trouble," "this is the one to stare at" are persuasion techniques, not analysis. Present the data and let the conclusion follow naturally. Analysis should read like a term sheet, not an op-ed.
+
+---
+
+# Voice & Framing — identity and stance
+
+## Say what you are, never what you're not
+
+Define by positive assertion. Don't build identity through negation. "We build vertical rockets" — not "we are not a traditional aerospace company, not a components supplier, not a consultancy."
+
+## No hidden negatives
+
+Some sentences look positive but structurally say "we don't do X." Flip them. "We design what we can build in volume" — not "We subordinate performance ambition to scalable manufacturability." "We ship weekly" — not "We don't let perfect block progress." If the sentence only makes sense by contrast with something you're rejecting, rewrite it as a direct claim.
+
+## Pass the "so what?" test
+
+Every sentence must earn its place. If it sounds authoritative but wouldn't help settle an argument in a room, cut it. If you could swap in any name — any company, any person, any product — and the sentence still works, it's empty.
+
+## Guide decisions, don't prescribe process
+
+A framework tells you what matters when you're making a choice. It doesn't create governance structures, escalation pathways, or approval chains. Those belong in an ops manual, not a strategy document or memo.
+
+---
+
+## Self-check
+
+Rules decay over long outputs — the longer you write, the more likely you revert to trained habits. After writing any prose longer than two paragraphs, re-read it against the preamble list before presenting it. Check for: hedging, over-explaining, verbosity, metadiscourse, trailing caveats, fake contradiction, and vague pronoun references.
+
+---
+
+## Licence of these rules
+
+MIT License
+
+Copyright (c) 2026 gundy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/docs/writing-standard.md

@@ -0,0 +1,85 @@
+# Writing standard
+
+Every surface a customer reads: report HTML, portal screens, README, docs. Two parts.
+
+## Part one: how to write
+
+`writing-rules.md` beside this file is the prose standard, and it applies to every sentence in those
+surfaces before anything below does. Read it in full once. The six rules it says to enforce first, because
+they are the ones a trained writer and a language model both break by instinct: no hedging, no
+over-explaining, keep it short, no metadiscourse, finish strong, and do not fake contradiction. If a
+sentence sounds like a language model wrote it, rewrite it.
+
+## Part two: the product's own rules
+
+Eight rules, each with the sentence that caused it.
+
+## One header per page, and nothing restating it
+
+A page names itself once. A line under the title earns its place only by saying something the title
+does not.
+
+- Before: `Home` over `Now`.
+- After: `Home`.
+
+## Example text goes inside the field
+
+A field's example belongs in its placeholder, where the reader is typing. A sentence above the field is
+read before the reader knows what the field is for.
+
+- Before, above the field: "A sentence is enough, or paste the whole thread."
+- After, in the field: "Need a quick check on AQUAPLUS for energy drinks in the US before Friday."
+
+## No caveat, no disclaimer, no "what this is not"
+
+Say what the search did and what happens next. Never define the product by negation.
+
+- Before: "What it is not. A clearance search. We drew no register conclusions and give no filing advice."
+- After: "A name that passes here goes on to clearance."
+
+## No engineering word in anything a client reads
+
+Error codes, connector names, routing tables and internal identifiers are not the reader's vocabulary.
+State the limit and its consequence.
+
+- Before: "the Japan adapter was unavailable this session (CONNECTION_CLOSED)".
+- After: "Case-law research could not be completed for Japan."
+
+## A count only when it changes what the reader does
+
+Register hit counts tell a lawyer how crowded a field is. Keep those. Activity counts measure the
+engine, not the answer.
+
+- Before: "Fifty-two meaning and connotation queries were run across the Latin, katakana and hiragana forms."
+- After: "Meaning was checked in three scripts; nothing loaded attaches to the name."
+
+## The product's own words for its own states
+
+A state has one name, used on the screen, in the report, in help and in the export.
+
+- Before: "No permissions".
+- After: "View reports".
+
+## The audit lives in the workbook and the MCP server, never on the page
+
+Every search run, every empty result and the working notes go to the audit workbook, and the MCP server
+answers questions about any of them. The page carries the finding.
+
+- Before: "Source routing attempted: Per the source-selection table, Japan is a non-US, non-EU
+  jurisdiction, so the applicable adapter is…"
+- After: nothing on the page. One row in the workbook.
+
+## A fault is fixed, or shown to the person who can act on it
+
+A customer cannot repair a missing coverage record. Narrating the failure to them turns our defect into
+their problem.
+
+- Before: "No coverage record was produced for this run. This section normally lists what each search
+  covered and what is still open… Ask us before relying on it."
+- After: the operator is told; the report carries the coverage that exists.
+
+## What holds these
+
+`enforcement.md` lists the classes a CI check refuses in a diff. Tone is not one of them, and no word
+list will ever catch it: a reviewer reads the rendered page as someone who has never seen this product,
+against `writing-rules.md`, and asks what they would think each sentence means.

package/driver/CHANGELOG.md

@@ -1,5 +1,11 @@
 # clearotron-driver
 
+## 0.3.2-beta.0
+
+### Patch Changes
+
+- 7cc0d29: Fixed: A report now lists every part of the search that was left open. One with a short name could be hidden by another line that happened to mention the same word. The overall result was never affected, only the list of what remained open.
+
 ## 0.3.1
 
 ### Patch Changes

package/driver/contract-e3-backlog.mjs

@@ -488,7 +488,7 @@ export const E3_BACKLOG = [
     where: "driver/stages.mjs:3231",
     surface: "stage-message",
     evidence: "- meters: {\"mark_similarity\":{...},\"goods_proximity\":{...},\"use\":{...},\"enforcer\":{...}} — all four present, each {\"token\",\"basis\",\"source\"}. … mark_similarity = high | medium | low. goods_proximity = high | medium | low. enforcer = high | medium | low | unknown. use = confirmed | not-confirmed | un",
-    reparsedBy: "driver/findings-model.mjs:813 parseFindingsJson; driver/verify.mjs:1108 checkFindingsSibling gates meters.*.source; finding_basis_source_missing",
+    reparsedBy: "driver/findings-model.mjs:813 parseFindingsJson; driver/verify.mjs:1127 checkFindingsSibling gates meters.*.source; finding_basis_source_missing",
     removedByMove: "NOTHING ON THE #850 PLAN REMOVES THIS",
   },
   {
@@ -684,7 +684,7 @@ export const E3_BACKLOG = [
     // because an un-anchorable row lands in the NOT-CHECKED slice, and that is coverage lost rather than
     // a pass.
     evidence: "is ONE of coverage-disposition | fact | rating | narrative — pick the one your own legal read says the correction IS: coverage-disposition (a coverage row / disposition placement is wrong or dishonest)",
-    reparsedBy: "driver/verify.mjs:784 CORRECTION_KIND_RE = /\\[kind:\\s*([a-z][a-z-]*)\\s*\\]/i → parseCorrectionKinds (verify.mjs:1007), consumed in pipelineInner() in pipeline.mjs for the run.jsonl `correction-kinds` histogram, which since #1558 also carries `kindChannelOk` — the counts are DERIVED from the parsed rows, and that key states whether the reviewer's kind channel produced anything at all rather than leaving a reader to infer it by comparing untyped against total. Telemetry only today",
+    reparsedBy: "driver/verify.mjs:803 CORRECTION_KIND_RE = /\\[kind:\\s*([a-z][a-z-]*)\\s*\\]/i → parseCorrectionKinds (verify.mjs:1026), consumed in pipelineInner() in pipeline.mjs for the run.jsonl `correction-kinds` histogram, which since #1558 also carries `kindChannelOk` — the counts are DERIVED from the parsed rows, and that key states whether the reviewer's kind channel produced anything at all rather than leaving a reader to infer it by comparing untyped against total. Telemetry only today",
     removedByMove: "NOTHING ON THE #850 PLAN REMOVES THIS",
   },
   {
@@ -697,7 +697,7 @@ export const E3_BACKLOG = [
     // `[on: -]` case went from a value to an ABSENCE — you omit the field — which is the one part a
     // reader could get wrong from the old wording, since there is no value meaning "no finding".
     evidence: "**AND EVERY FLAG CARRIES WHICH FINDING IT IS ABOUT** — the `on` field, an array of ordinals. Same rule as `kind`: you send the values, the driver renders the token.",
-    reparsedBy: "driver/verify.mjs:801 CORRECTION_ON_RE = /\\[on:\\s*([0-9,\\s-]*?)\\s*\\]/i. SKILL-FILE ONLY — the stage message at stages.mjs:1842-1877 never mentions `[on:]`. This is #850's \"the element shape is in the skill file, not the stage message\" in its purest form: an E3 lint reading stages.mjs alone sees the [kind:] token and misses its twin",
+    reparsedBy: "driver/verify.mjs:820 CORRECTION_ON_RE = /\\[on:\\s*([0-9,\\s-]*?)\\s*\\]/i. SKILL-FILE ONLY — the stage message at stages.mjs:1842-1877 never mentions `[on:]`. This is #850's \"the element shape is in the skill file, not the stage message\" in its purest form: an E3 lint reading stages.mjs alone sees the [kind:] token and misses its twin",
     removedByMove: "NOTHING ON THE #850 PLAN REMOVES THIS",
   },
   {

package/driver/contract-vocabulary.mjs

@@ -16,9 +16,9 @@
 // extractor never sees:
 //
 //   D1 verify.mjs:940   fail(`connotation_${reason}:…`)      — reason iterates the table at line 894
-//   D2 verify.mjs:704   fail(String(e.message))              — parseFindingsJson throws token-first
-//   D3 verify.mjs:1165   checkJson: fail(String(e.message))   — FIVE parsers reach this one site
-//   D4 verify.mjs:1603  parseCoverageLedgerJson, same shape
+//   D2 verify.mjs   fail(String(e.message))              — parseFindingsJson throws token-first
+//   D3 verify.mjs:1184   checkJson: fail(String(e.message))   — FIVE parsers reach this one site
+//   D4 verify.mjs  parseCoverageLedgerJson, same shape
 //   D5 verify.mjs:1504  fail(`${unaccounted[0].token}:…`)    — token minted in a DATA ROW
 //   D6 verify.mjs:1567  fail(`${violations[0].token}…`)      — validatePlanFeasibility in register-plan.mjs
 //   D7 verify.mjs:1558  fail(`${v2[0].token}${detail}…`)     — register-plan.mjs:2018 disclosureTextByAxis
@@ -99,7 +99,7 @@ export const VOCABULARY = [
   { token: "ratified_form_unread", stages: ["synthesis"], site: "driver/verify.mjs" },
   { token: "coverage_recommendation", stages: ["synthesis"], site: "driver/verify.mjs" },
   { token: "coverage_gap_unexplained", stages: ["synthesis"], site: "driver/verify.mjs" },
-  { token: "finding", stages: ["synthesis"], site: "driver/verify.mjs:704", family: "driver/findings-model.mjs (token-first throws; `finding_*` and `findings_*`)", dynamic: "D2" },
+  { token: "finding", stages: ["synthesis"], site: "driver/verify.mjs", family: "driver/findings-model.mjs (token-first throws; `finding_*` and `findings_*`)", dynamic: "D2" },
 
   // ── register-digest ────────────────────────────────────────────────────────────────────────────────
   { token: "coverage_form_damaged", stages: ["register-digest"], site: "driver/verify.mjs" },
@@ -109,16 +109,16 @@ export const VOCABULARY = [
   { token: "coverage_form_missing", stages: ["register-digest"], site: "driver/verify.mjs" },
   { token: "coverage_form_empty", stages: ["register-digest"], site: "driver/verify.mjs" },
   { token: "coverage_status_offenum", stages: ["register-digest"], site: "driver/verify.mjs:2050" },
-  { token: "coverage_deferred_unaccounted", stages: ["register-digest"], site: "driver/verify.mjs:1504 coverageFormFail", family: "driver/register-plan.mjs:1642 PROVIDER_HARD_ERROR_PREFIX — token on a data row", dynamic: "D5" },
+  { token: "coverage_deferred_unaccounted", stages: ["register-digest"], site: "driver/verify.mjs:1510 coverageFormFail", family: "driver/register-plan.mjs:1642 PROVIDER_HARD_ERROR_PREFIX — token on a data row", dynamic: "D5" },
   { token: "coverage_clean_unexecuted", stages: ["register-digest"], site: "driver/verify.mjs, the matterContext validator", family: "driver/register-plan.mjs:1417 validatePlanFeasibility", dynamic: "D6" },
   { token: "coverage_clean_skipped", stages: ["register-digest"], site: "driver/verify.mjs, the matterContext validator", family: "driver/register-plan.mjs:1766 searchedJurisdictionsFromPlan", dynamic: "D6" },
   { token: "coverage_clean_unverified_incomplete", stages: ["register-digest"], site: "driver/verify.mjs, the matterContext validator", family: "driver/register-plan.mjs:2018 disclosureTextByAxis", dynamic: "D7" },
   { token: "coverage_clean_tainted", stages: ["register-digest"], site: "driver/verify.mjs" },
-  { token: "coverage_ledger_", stages: ["register-digest"], site: "driver/verify.mjs:1603", family: "driver/coverage-ledger.mjs (parseCoverageLedgerJson token-first throws)", dynamic: "D4" },
-  { token: "coverage_key_unknown", stages: ["register-digest"], site: "driver/verify.mjs:1603", family: "driver/coverage-ledger.mjs", dynamic: "D4" },
-  { token: "coverage_axis_", stages: ["register-digest"], site: "driver/verify.mjs:1603", family: "driver/coverage-ledger.mjs", dynamic: "D4" },
-  { token: "coverage_status_invalid", stages: ["register-digest"], site: "driver/verify.mjs:1603", family: "driver/coverage-ledger.mjs", dynamic: "D4" },
-  { token: "coverage_classes_invalid", stages: ["register-digest"], site: "driver/verify.mjs:1603", family: "driver/coverage-ledger.mjs", dynamic: "D4" },
+  { token: "coverage_ledger_", stages: ["register-digest"], site: "driver/verify.mjs", family: "driver/coverage-ledger.mjs (parseCoverageLedgerJson token-first throws)", dynamic: "D4" },
+  { token: "coverage_key_unknown", stages: ["register-digest"], site: "driver/verify.mjs", family: "driver/coverage-ledger.mjs", dynamic: "D4" },
+  { token: "coverage_axis_", stages: ["register-digest"], site: "driver/verify.mjs", family: "driver/coverage-ledger.mjs", dynamic: "D4" },
+  { token: "coverage_status_invalid", stages: ["register-digest"], site: "driver/verify.mjs", family: "driver/coverage-ledger.mjs", dynamic: "D4" },
+  { token: "coverage_classes_invalid", stages: ["register-digest"], site: "driver/verify.mjs", family: "driver/coverage-ledger.mjs", dynamic: "D4" },
   { token: "plan_execution_unreadable", stages: ["register-digest", "narrative-refutation"], site: "driver/verify.mjs:1496, 1712" },
 
   // ── matter-frame / prelim-variants / blind-frame / frame-diff ──────────────────────────────────────
@@ -130,7 +130,7 @@ export const VOCABULARY = [
   { token: "variantmodel_term_markup", stages: ["prelim-variants"], site: "driver/verify.mjs" },
   { token: "variantmodel_missing", stages: ["prelim-variants"], site: "driver/verify.mjs:1153, 1212" },
   // Recovered during E2 authoring, absent from the draft census: variant-manifest.json is strict-parsed
-  // through checkSiblingJson (verify.mjs:1178) → checkJson (:742), so the WHOLE variantmodel_* family
+  // through checkSiblingJson (verify.mjs:1197) → checkJson (:742), so the WHOLE variantmodel_* family
   // reaches prelim-variants, not just the four literal tokens above.
   // CONVERSION 3 widened this family's SOURCE without widening its prefix. `acceptPrelimVariants` raises
   // `variantmodel_scope_layer_invalid`, `_scope_status_invalid`, `_scope_item_missing` and `_scope_pipe`
@@ -319,7 +319,8 @@ export const STAGE_UNREACHABLE_VALIDATORS = [
  *
  * The drift is CLUSTERED, not random: 34, 35, 36, 52 recur. That is one insertion above a block moving
  * every citation below it, all at once, silently, in a PR that was about something else entirely. A
- * reader following `coverage_ledger_ → verify.mjs:1603` lands on a comment 219 lines from the dispatcher.
+ * reader following `coverage_ledger_ → verify.mjs` to line 1603 landed on a comment 219 lines from the
+ * dispatcher. (That number is the 2026 measurement's own datum, not a pointer into today's file.)
  *
  * `symbol:` names a thing instead — a function, a constant, an exported name. It survives every move.
  * `site:` stays as the hint it always was, and `contract-audit.test.mjs` asserts that any `symbol:` a row
@@ -419,9 +420,9 @@ export const INNER_CODES = Object.freeze([
   // CONNOTATION_FORM_REASONS at connotation-search.mjs:1731 is `CONNOTATION_REASONS` minus
   // `no_recorded_queries`, and the `connotation_` family row (dynamic D1) is declared against exactly
   // that list. The four call codes are folded by a template — `connotation_${callFail.reason}` at
-  // verify.mjs:1013 — so they are namespaced by construction rather than one branch at a time.
+  // verify.mjs — so they are namespaced by construction rather than one branch at a time.
   { code: "call_never_made", mints: ["driver/connotation-search.mjs:2007"], rollsUpTo: ["connotation_call_never_made"],
-    why: "CALL_AUDIT_ROWS. The typed transport's four call states, handed in by disposition-call-audit.mjs and namespaced at verify.mjs:1013." },
+    why: "CALL_AUDIT_ROWS. The typed transport's four call states, handed in by disposition-call-audit.mjs and namespaced at verify.mjs." },
   { code: "call_truncated", mints: ["driver/connotation-search.mjs:2008"], rollsUpTo: ["connotation_call_truncated"],
     why: "As call_never_made — same table, same projection." },
   { code: "call_schema_violation", mints: ["driver/connotation-search.mjs:2009"], rollsUpTo: ["connotation_call_schema_violation"],

package/driver/gateway.mjs

@@ -2596,29 +2596,45 @@ export function correctionHint(lastFail, { gridLedgerName = "common-law-grid.jso
     const dropped = (lastFail.match(/connotation_query_unrecorded:(.+)$/s) || [])[1] || "";
     // ── TWO FAULTS, TWO REMEDIES, and sending the wrong one is what made this permanent ────────────
     //
-    // The gate marks each dropped query `[absent from the ledger]` or `[unmatched; nearest recorded: …]`.
-    // Absent means the search did not run and must. Unmatched means it DID run and the ledger's spelling
-    // differs beyond punctuation — re-running it changes nothing, and telling a seat to re-run is how a
-    // stage fails four times with the same string. Where both appear, both sentences are sent.
+    // The gate marks each dropped query `[unmatched; nearest recorded: …]` or `[no recorded query
+    // resembles this one]`, and the difference is what the gate can SEE, not what happened.
+    //
+    // UNMATCHED is knowable: something close is recorded, so the search ran and the wording differs.
+    // Re-running changes nothing, and telling a seat to re-run is how a stage fails four times with the
+    // same string.
+    //
+    // NO RESEMBLANCE IS NOT KNOWABLE, and this hint used to pretend otherwise. It said the query was
+    // missing and to go and run it — but a query recorded under a translation, a transliteration or the
+    // seat's own rewording resembles nothing and has already run, and that seat was then sent round the
+    // same loop the unmatched branch exists to break. The gate cannot tell the two apart; no threshold
+    // can, and a threshold that could would be one that hides a query nobody ran.
+    //
+    // So this branch stops asserting and hands over both repairs. Both are cheap, a seat can tell which
+    // applies by looking at its own ledger, and neither wastes an attempt: if the search did run, fix
+    // the row's wording; if it did not, run it and append the row. Where both labels appear, both
+    // sentences are sent, as before.
     const anyUnmatched = /\[unmatched; nearest recorded:/.test(dropped);
-    const anyAbsent = /\[absent from the ledger\]/.test(dropped);
-    hint = anyUnmatched && !anyAbsent
+    const anyUnresembled = /\[no recorded query resembles this one\]/.test(dropped);
+    hint = anyUnmatched && !anyUnresembled
       ? `these dictated meaning queries ARE recorded in ${gridLedgerName} extras.pr_risk[] under a ` +
         `different wording, which is why the driver cannot match them: ${dropped}. Do NOT re-run them — ` +
         `the search already ran and its results are already in the ledger. EDIT each row's \`query\` ` +
         `field to the query text EXACTLY as the task message dictates it, character for character, and ` +
         `leave its results untouched. The driver matches your rows to its list by that text`
-      : `every dictated meaning query owes a row, including the ones that find nothing — these are ` +
-      `missing from ${gridLedgerName} extras.pr_risk[]: ${dropped}. A query that returned NO results is ` +
-      `not an excuse to omit it: record it with an empty results array, which is the receipt that the ` +
-      `search RAN and came back clean. That is the whole point of the sweep — on an "offensive meaning" ` +
-      `query the empty answer IS the good news, and a missing row is indistinguishable from a search ` +
-      `nobody performed. Re-run ONLY the listed queries, append a row per query to extras.pr_risk[] ` +
-      `whether or not it has hits, and leave every row already recorded exactly as it is. Record each ` +
-      `query's text EXACTLY as the task message dictates it — the driver matches your rows to its list by ` +
-      `the query text, so a reworded or re-punctuated query reads as one you never ran. Where a query is ` +
-      `marked \`[unmatched; nearest recorded: …]\` it is already in the ledger under that wording: edit ` +
-      `that row's \`query\` to the dictated text rather than running the search again`;
+      : `the driver cannot match these dictated meaning queries to any row in ${gridLedgerName} ` +
+      `extras.pr_risk[]: ${dropped}. That means one of two things and the driver cannot tell which, so ` +
+      `check your own ledger and do whichever applies — both are cheap. IF THE SEARCH ALREADY RAN and ` +
+      `you recorded it under different wording — a translation, a reordering, your own phrasing — do ` +
+      `NOT run it again. EDIT that row's \`query\` field to the query text EXACTLY as the task message ` +
+      `dictates it, character for character, and leave its results untouched. IF IT NEVER RAN, run it ` +
+      `now and append a row to extras.pr_risk[]. A query that returned NO results still owes its row: ` +
+      `record it with an empty results array, which is the receipt that the search RAN and came back ` +
+      `clean. On an "offensive meaning" query the empty answer IS the good news, and a missing row is ` +
+      `indistinguishable from a search nobody performed. Either way, record each query's text EXACTLY ` +
+      `as the task message dictates it — the driver matches your rows to its list by that text, so a ` +
+      `reworded query reads as one you never ran. Touch ONLY the listed queries and leave every other ` +
+      `recorded row exactly as it is. Where a query is marked \`[unmatched; nearest recorded: …]\` the ` +
+      `driver has already found its row for you: edit that row's \`query\` and do not search again`;
   } else if (/connotation_search_missing/.test(lastFail)) {
     // — was "your PR / reputational section claims a clean meaning … but the ledger recorded ZERO
     // searches", which under the `ensure` prefix instructed the model to make the unbacked claim.

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.1",
+  "version": "0.3.2-beta.0",
   "license": "AGPL-3.0-only",
   "description": "Deterministic driver for the trademark clearance workflow: orchestration in code (fan-out, fan-in barrier, gating, retries); the model does judgment leaves only, through a reasoning CLI spawned per stage.",
   "engines": {

package/driver/publish/render-knockout.mjs

@@ -53,6 +53,7 @@ import { demoBannerHtml } from './render.mjs';   // — the SAME banner the clea
 // fail-open; re-deriving either in a renderer would be this file starting a second status vocabulary,
 // which is the thing providers/_shared/screen.mjs exists to prevent.
 import { makeClassifyStatus, isAllClass } from '../../providers/_shared/screen.mjs';
+import { saysSomethingNew } from '../../shared/says-something-new.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -1336,32 +1337,11 @@ const SCOPE_BLOCK_TEXT = 'What this is. A fast screen for obvious blockers to us
   + 'goes on to clearance. Every conflict above links to the material we found. The audit workbook holds '
   + 'every search run, every empty result and the working notes. Register data.';
 
-/** Words that carry no claim, so their presence or absence says nothing about what a sentence asserts. */
-const STOPWORDS = new Set(['a', 'an', 'and', 'are', 'as', 'at', 'be', 'been', 'but', 'by', 'can', 'do',
-  'does', 'each', 'for', 'from', 'has', 'have', 'here', 'in', 'is', 'it', 'its', 'no', 'not', 'of', 'on',
-  'or', 'that', 'the', 'their', 'them', 'there', 'these', 'they', 'this', 'to', 'up', 'was', 'we', 'were',
-  'what', 'when', 'which', 'will', 'with', 'you', 'your']);
-
-const contentWords = (s) => String(s ?? '').toLowerCase().replace(/[^a-z0-9\s-]/g, ' ')
-  .split(/\s+/).filter((w) => w.length > 2 && !STOPWORDS.has(w));
-
-/**
- * Does this line assert anything the reference text does not already assert?
- *
- * TRUE unless every content word in the line is already in the reference. An empty line has nothing to
- * say and returns false; a line with one unfamiliar word is kept. Singular/plural is folded so that
- * "conclusion" does not read as new beside "conclusions".
- */
-function saysSomethingNew(line, reference) {
-  // The stem must be IDEMPOTENT on the singular, or the fold does nothing: an earlier form stripped
-  // "es" and turned "gives" into "giv" while leaving "give" alone, so the two never matched and every
-  // caveat looked new. Strip one trailing "s" and nothing else.
-  const stem = (w) => w.replace(/ies$/, 'y').replace(/s$/, '');
-  const known = new Set(contentWords(reference).map(stem));
-  const words = contentWords(line);
-  if (!words.length) return false;
-  return words.some((w) => !known.has(stem(w)));
-}
+// THE CAVEAT FILTER IS SHARED, NOT LOCAL. `saysSomethingNew` was defined here and is now in
+// `shared/says-something-new.mjs`, because the writing-standard check asks the identical question of a
+// page's lede against its title. Two definitions of one rule is one definition and one imitation of it.
+// The stopword set and the idempotent stem travel with it; the reference text below stays here, because
+// it is this page's own words and nothing else's.
 
 function readBlock(m, framework) {
   const factors = (m.factors ?? []).filter((s) => typeof s === 'string' && s.trim());