@event4u/agent-config 14.13.0 → 14.14.1

package/src/scripts/_lib/routing_corpus.ts

@@ -0,0 +1,307 @@
+/**
+ * The corpus and catalogue substrate for the two routing measurements of
+ * `road-to-governed-harness-evolution` — step 5.1 (description vs body) and
+ * step 6.4 (delivery sets).
+ *
+ * ONE LOADER, TWO MEASUREMENTS. Both runs need the same three things: the
+ * frozen train/holdout partition, the trigger cases, and the skill catalogue
+ * the prompts are ranked against. Two loaders over one corpus is how two
+ * measurements start disagreeing about what they measured, so there is one.
+ *
+ * THE SEAL IS ENFORCED BY REFUSAL, NOT BY FILTERING. The holdout partition
+ * frozen in `agents/evidence/analysis/trigger-corpus-holdout-2026-08-30.md`
+ * says: no analyzer authored in Phase 5 may read the sealed corpora. So
+ * `loadTrainCases` never opens a holdout `evals/triggers.json` at all — the
+ * partition is computed from the DIRECTORY NAME, before any file is read.
+ * Filtering after the read would satisfy the letter and not the seal.
+ *
+ * The seal covers the corpus files and not the catalogue: a holdout skill's
+ * `SKILL.md` is still ranked against, because removing it would measure a
+ * catalogue that does not exist. The boundary is stated in the 5.1
+ * pre-registration rather than left to be inferred here.
+ *
+ * NO SCORER OF ITS OWN. Every score comes from `src/shared/skillRanking.ts`,
+ * the module the production ranker and the MCP handler already share. A second
+ * scorer in a measurement module would measure the measurement.
+ *
+ * Pure of network and of clock; reads files and nothing else.
+ */
+import * as fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import * as path from 'node:path';
+
+import { scoreSkill, tokenize, type RankableSkill } from '../../shared/skillRanking.js';
+
+/**
+ * The partition constant the freeze artefact fixes. Changing it re-partitions
+ * the corpus and voids every result measured under the old one, which is why
+ * it is a named export a test can pin rather than a literal.
+ */
+export const HOLDOUT_CEILING = 51;
+
+export type Partition = 'holdout' | 'train';
+
+/** `holdout iff sha256(<skill-directory-name>)[0] < 51`, from the freeze artefact. */
+export function partitionOf(skill: string): Partition {
+    const bucket = parseInt(createHash('sha256').update(skill).digest('hex').slice(0, 2), 16);
+    return bucket < HOLDOUT_CEILING ? 'holdout' : 'train';
+}
+
+/** One adjudicated case: a prompt, and whether the owning skill must be delivered. */
+export interface CorpusCase {
+    readonly skill: string;
+    readonly prompt: string;
+    /** `true` = positive (must be delivered) · `false` = negative (must not). */
+    readonly expect: boolean;
+    /** Step 2.3's vocabulary where the file declares it; 876 of 931 cases do not. */
+    readonly caseClass: 'exemplar' | 'near-miss' | 'counterexample' | null;
+    readonly language: string | null;
+}
+
+interface RawQuery {
+    q?: unknown;
+    trigger?: unknown;
+    class?: unknown;
+    language?: unknown;
+}
+
+/**
+ * The two corpus shapes this tree carries.
+ *
+ * `queries[]` is the modern one. Two train files — `brand-asset-generation` and
+ * `estimate-ticket` — are the legacy `should_trigger` / `should_not_trigger`
+ * pair that step 2.3 grandfathered, and `lint_skill_trigger_corpus` returns
+ * before its class rules for exactly those two. A reader that understood only
+ * the modern shape would drop them SILENTLY, which is worse than refusing them:
+ * the run would report 80 train corpora where the partition says 82 and nothing
+ * would say which two were missing. So both shapes are read, and
+ * `legacyShaped` records which file used which.
+ */
+interface RawCorpus {
+    queries?: RawQuery[];
+    should_trigger?: unknown;
+    should_not_trigger?: unknown;
+}
+
+export function skillsDir(repoRoot: string): string {
+    return path.join(repoRoot, 'src', 'skills');
+}
+
+/**
+ * Is this `src/skills/<name>` entry test scaffolding rather than a skill?
+ *
+ * A `__`-prefixed directory is scaffolding by convention, and a real skill can
+ * never be named one: `skill.schema.json` pins `name` to `^[a-z][a-z0-9-]*$`
+ * and requires it to match the parent directory, so a leading underscore fails
+ * `validate_frontmatter`. This predicate therefore cannot hide a shipped skill.
+ *
+ * WHY IT EXISTS, measured rather than assumed.
+ * `tests/scripts/lint_originality.test.ts:64` writes a re-skin fixture to
+ * `src/skills/__origtest_reskin_fixture/SKILL.md` in the REAL tree and removes
+ * it in `afterEach`, because the linter resolves its corpus from a
+ * module-level ROOT and takes no root argument. During that window any
+ * concurrently-running test file that counts the catalogue sees 300 where the
+ * commit holds 299 — which is what failed
+ * `tests/scripts/routing_signal_measurement.test.ts` on
+ * `Node Tests (ubuntu-latest, shard 2/4)` in runs 33418425604 and 33424783559,
+ * intermittently, while passing in isolation and passing on the next run over
+ * two markdown files nothing reads.
+ *
+ * Reproduced locally before this line was written: with the fixture present on
+ * disk the assertion fails `300` vs `299`, character for character the CI
+ * message; with this predicate active it passes.
+ *
+ * Excluding the prefix here rather than threading a root through the linter is
+ * the smaller change by an order of magnitude: ROOT is baked into ten
+ * module-level constants there, and refactoring a shipped gate to suit a test
+ * is a worse trade than a naming convention the tree already follows.
+ */
+export function isScaffoldingSkillDir(name: string): boolean {
+    return name.startsWith('__');
+}
+
+/** Every skill directory that carries a trigger corpus, with its partition. */
+export function corpusSkills(repoRoot: string): { skill: string; partition: Partition }[] {
+    const dir = skillsDir(repoRoot);
+    if (!fs.existsSync(dir)) return [];
+    return fs
+        .readdirSync(dir)
+        .sort()
+        .filter((skill) => !isScaffoldingSkillDir(skill))
+        .filter((skill) => fs.existsSync(path.join(dir, skill, 'evals', 'triggers.json')))
+        .map((skill) => ({ skill, partition: partitionOf(skill) }));
+}
+
+/**
+ * The train cases. A holdout corpus is never opened — the partition is decided
+ * from the directory name and the sealed path is skipped before any read.
+ */
+export function loadTrainCases(repoRoot: string): CorpusCase[] {
+    const dir = skillsDir(repoRoot);
+    const out: CorpusCase[] = [];
+    for (const { skill, partition } of corpusSkills(repoRoot)) {
+        if (partition === 'holdout') continue;
+        const raw = JSON.parse(
+            fs.readFileSync(path.join(dir, skill, 'evals', 'triggers.json'), 'utf8'),
+        ) as RawCorpus;
+        if (Array.isArray(raw.queries)) {
+            for (const q of raw.queries) {
+                if (typeof q.q !== 'string' || typeof q.trigger !== 'boolean') continue;
+                const declared = typeof q.class === 'string' ? q.class : null;
+                out.push({
+                    skill,
+                    prompt: q.q,
+                    expect: q.trigger,
+                    caseClass:
+                        declared === 'exemplar' ||
+                        declared === 'near-miss' ||
+                        declared === 'counterexample'
+                            ? declared
+                            : null,
+                    language: typeof q.language === 'string' ? q.language : null,
+                });
+            }
+            continue;
+        }
+        for (const [key, expect] of [
+            ['should_trigger', true],
+            ['should_not_trigger', false],
+        ] as const) {
+            const list = raw[key];
+            if (!Array.isArray(list)) continue;
+            for (const prompt of list) {
+                if (typeof prompt !== 'string') continue;
+                out.push({ skill, prompt, expect, caseClass: null, language: null });
+            }
+        }
+    }
+    return out;
+}
+
+/** Which train corpora use the legacy shape. Reported so the count is explainable. */
+export function legacyShaped(repoRoot: string): string[] {
+    const dir = skillsDir(repoRoot);
+    const out: string[] = [];
+    for (const { skill, partition } of corpusSkills(repoRoot)) {
+        if (partition === 'holdout') continue;
+        const raw = JSON.parse(
+            fs.readFileSync(path.join(dir, skill, 'evals', 'triggers.json'), 'utf8'),
+        ) as RawCorpus;
+        if (!Array.isArray(raw.queries)) out.push(skill);
+    }
+    return out;
+}
+
+/** A catalogue entry: what the ranker sees, plus the body the 5.1 arm adds. */
+export interface CatalogueEntry extends RankableSkill {
+    readonly name: string;
+    readonly description: string;
+    readonly personas: readonly string[];
+    /** SKILL.md with its frontmatter removed. Empty when the file has none. */
+    readonly body: string;
+}
+
+/** Minimal frontmatter split. Returns `[block, body]`; `['', text]` when absent. */
+export function splitFrontmatter(text: string): [string, string] {
+    if (!text.startsWith('---')) return ['', text];
+    const end = text.indexOf('\n---', 3);
+    if (end === -1) return ['', text];
+    return [text.slice(3, end), text.slice(end + 4)];
+}
+
+/** `name`, `description` and `personas` out of a frontmatter block. */
+export function readMeta(block: string): { name: string; description: string; personas: string[] } {
+    let name = '';
+    let description = '';
+    const personas: string[] = [];
+    let inPersonas = false;
+    for (const raw of block.split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (inPersonas && /^ {2}- /.test(line)) {
+            personas.push(line.slice(4).trim().replace(/^["']|["']$/g, ''));
+            continue;
+        }
+        inPersonas = false;
+        const m = /^([a-zA-Z_][\w-]*)[ \t]*:[ \t]*(.*)$/.exec(line);
+        if (!m) continue;
+        const key = m[1] as string;
+        const value = (m[2] as string).trim().replace(/^["']|["']$/g, '');
+        if (key === 'personas' && value === '') inPersonas = true;
+        else if (key === 'name') name = value;
+        else if (key === 'description') description = value;
+    }
+    return { name, description, personas };
+}
+
+/** Every skill directory`s `SKILL.md`, name-sorted. The ranking universe. */
+export function loadCatalogue(repoRoot: string): CatalogueEntry[] {
+    const dir = skillsDir(repoRoot);
+    if (!fs.existsSync(dir)) return [];
+    const out: CatalogueEntry[] = [];
+    for (const skill of fs.readdirSync(dir).sort()) {
+        if (isScaffoldingSkillDir(skill)) continue;
+        const file = path.join(dir, skill, 'SKILL.md');
+        if (!fs.existsSync(file)) continue;
+        const [block, body] = splitFrontmatter(fs.readFileSync(file, 'utf8'));
+        const meta = readMeta(block);
+        out.push({
+            name: meta.name || skill,
+            description: meta.description,
+            personas: meta.personas,
+            body,
+        });
+    }
+    return out;
+}
+
+/** The two 5.1 arms. `description` is today's production condition. */
+export const ARMS = ['description', 'description+body'] as const;
+export type Arm = (typeof ARMS)[number];
+
+/**
+ * The indexed term set per arm.
+ *
+ * The `description` arm reproduces `skillTerms(skill, {})` exactly — same
+ * inputs, same tokenizer — so the control arm IS the shipped behaviour rather
+ * than a re-implementation of it.
+ */
+export function armTerms(entry: CatalogueEntry, arm: Arm): Set<string> {
+    const parts = [entry.name, entry.description];
+    if (arm === 'description+body') parts.push(entry.body);
+    return tokenize(parts.join(' '));
+}
+
+export interface RankedName {
+    readonly name: string;
+    readonly score: number;
+}
+
+/**
+ * Top-k by score, ties broken on name — the total order `rankSkills` already
+ * defines. Zero scores are dropped, because a skill the scorer gives 0 is not
+ * delivered by the shipped ranker either.
+ */
+export function topK(
+    prompt: string,
+    catalogue: readonly CatalogueEntry[],
+    terms: ReadonlyMap<string, Set<string>>,
+    k: number,
+): RankedName[] {
+    const taskTerms = tokenize(prompt);
+    const rows: RankedName[] = [];
+    for (const entry of catalogue) {
+        const t = terms.get(entry.name);
+        if (t === undefined) continue;
+        const score = scoreSkill(taskTerms, entry, t);
+        if (score > 0) rows.push({ name: entry.name, score });
+    }
+    rows.sort((a, b) => b.score - a.score || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return rows.slice(0, k);
+}
+
+/** Term sets for one arm, keyed by the name `topK` ranks on. */
+export function termIndex(catalogue: readonly CatalogueEntry[], arm: Arm): Map<string, Set<string>> {
+    const index = new Map<string, Set<string>>();
+    for (const entry of catalogue) index.set(entry.name, armTerms(entry, arm));
+    return index;
+}

package/src/scripts/_lib/routing_index_input.ts

@@ -0,0 +1,104 @@
+/**
+ * routing_index_input — what the skill index is built OVER, derived from the
+ * 5.1 verdict file (`road-to-governed-harness-evolution` step 6.5).
+ *
+ * Step 6.5 reads: *"Index the body only if 5.1 measured a signal. Otherwise
+ * description-only. verify: the indexer`s input set derives from the 5.1
+ * verdict file."*
+ *
+ * SO THE ANSWER IS NOT WRITTEN HERE. This module contains no opinion about the
+ * body. It opens
+ * `agents/evidence/analysis/routing-body-signal-verdict.json`, reads
+ * `body_signal.verdict`, and returns the input set that verdict licenses. Flip
+ * the file and the input set flips; delete the file and it falls back. A module
+ * that hardcoded `description` would satisfy the step`s OUTCOME today and fail
+ * its verify, because the outcome would not derive from anything.
+ *
+ * FAIL-CLOSED, IN THE DIRECTION THAT COSTS LESS. Missing file, unparseable
+ * JSON, unknown verdict token, or a missing `proxy_to_real_fidelity` field all
+ * resolve to **description-only** with the reason recorded. Only the literal
+ * token `signal` widens the index. The asymmetry is deliberate: a stale or
+ * broken record must never be able to widen what the suite indexes, and the
+ * measured cost of widening on a `harmful` verdict is +7.22 pp of false
+ * activation.
+ *
+ * WHY THE FIDELITY FIELD GATES THE READ. The 5.1 verdict ships its own bound —
+ * `proxy_to_real_fidelity`, null and unmeasured-by-construction — precisely so
+ * a consumer cannot take the conclusion without it. A record that has lost that
+ * field is a record whose provenance has been edited, and this resolver refuses
+ * it rather than trusting the half that survived.
+ *
+ * Pure of network and of clock; reads one file.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Where step 5.1 writes its machine-readable verdict. */
+export const VERDICT_REL = 'agents/evidence/analysis/routing-body-signal-verdict.json';
+
+/** The two input sets step 6.5 can resolve to. Ordered, so they are comparable. */
+export const DESCRIPTION_ONLY = ['name', 'description'] as const;
+export const DESCRIPTION_AND_BODY = ['name', 'description', 'body'] as const;
+
+export interface IndexInput {
+    readonly fields: readonly string[];
+    /** The token read from the verdict file, or `null` when none could be read. */
+    readonly verdict: string | null;
+    readonly reason: string;
+    /** `true` only when the verdict file licensed the wider set. */
+    readonly indexesBody: boolean;
+}
+
+const descriptionOnly = (verdict: string | null, reason: string): IndexInput => ({
+    fields: DESCRIPTION_ONLY,
+    verdict,
+    reason,
+    indexesBody: false,
+});
+
+/**
+ * The input set the 5.1 verdict at `repoRoot` licenses.
+ *
+ * `verdictPath` exists so a test can point the resolver at a fixture record
+ * instead of writing to the tracked one.
+ */
+export function resolveIndexInput(repoRoot: string, verdictPath?: string): IndexInput {
+    const file = verdictPath ?? path.join(repoRoot, VERDICT_REL);
+    let parsed: Record<string, unknown>;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>;
+    } catch {
+        return descriptionOnly(null, `no readable 5.1 verdict at ${VERDICT_REL} — fail-closed`);
+    }
+    if (parsed['proxy_to_real_fidelity'] === undefined) {
+        return descriptionOnly(
+            null,
+            'the 5.1 verdict carries no proxy_to_real_fidelity bound — refused, fail-closed',
+        );
+    }
+    const body = parsed['body_signal'];
+    const token =
+        typeof body === 'object' && body !== null
+            ? (body as Record<string, unknown>)['verdict']
+            : undefined;
+    if (typeof token !== 'string') {
+        return descriptionOnly(null, 'the 5.1 verdict carries no body_signal.verdict — fail-closed');
+    }
+    if (token === 'signal') {
+        return {
+            fields: DESCRIPTION_AND_BODY,
+            verdict: token,
+            reason: 'the 5.1 verdict is `signal` — the body is indexed',
+            indexesBody: true,
+        };
+    }
+    return descriptionOnly(token, `the 5.1 verdict is \`${token}\`, not \`signal\` — description-only`);
+}
+
+/** The `Arm` name the routing corpus uses for the resolved input set. */
+export function resolveIndexArm(
+    repoRoot: string,
+    verdictPath?: string,
+): 'description' | 'description+body' {
+    return resolveIndexInput(repoRoot, verdictPath).indexesBody ? 'description+body' : 'description';
+}

package/src/scripts/_lib/rule_injection.ts

@@ -214,13 +214,34 @@ export function selectForInjection(
     repoRoot: string,
     matches: TierRuleMatch[],
     capBytes: number,
+    shortlist?: readonly string[] | null,
 ): SelectionResult {
     const bodyBytes = new Map<string, number>();
     for (const m of matches) {
         const body = loadRuleBody(repoRoot, m.id);
         bodyBytes.set(m.id, body === null ? 0 : bytesOf(body));
     }
-    const ranked = [...matches].sort((a, b) => b.score - a.score || a.order - b.order);
+    // STEP 6.3 — the optional lexical shortlist, as a TIE-BREAK and nothing more.
+    //
+    // Absent (the default), the cap order is exactly what it was: score, then
+    // router order. Present, it sits BETWEEN them, never above `score` — the
+    // matcher's verdict is read first and the shortlist only orders what the
+    // matcher already tied. Membership is untouched in both directions: a
+    // shortlisted id the matcher did not return is not in `matches` and so is
+    // never consulted, and no matched id is dropped for being unshortlisted
+    // (it sorts at Infinity, behind the shortlisted ones, and still competes
+    // for the cap). That is `_lib/lexical_shortlist.ts`'s "never decides
+    // alone" expressed at the one place the cap actually binds.
+    const rank = new Map<string, number>();
+    for (const [i, id] of (shortlist ?? []).entries()) {
+        if (!rank.has(id)) rank.set(id, i);
+    }
+    const ranked = [...matches].sort(
+        (a, b) =>
+            b.score - a.score ||
+            (rank.get(a.id) ?? Infinity) - (rank.get(b.id) ?? Infinity) ||
+            a.order - b.order,
+    );
     const selected: TierRuleMatch[] = [];
     const dropped: TierRuleMatch[] = [];
     let total = 0;

package/src/scripts/_lib/runtime_journal.ts

@@ -173,7 +173,7 @@ import type { DatabaseSync } from 'node:sqlite';
 
 import { current_branch, git_common_dir, git_dir } from './git_common_dir.js';
 import type { TerminalState } from './outcome_envelope.js';
-import { RUN_TERMINAL_STATES } from './outcome_vocabularies.js';
+import { readRunTerminalState, RUN_TERMINAL_STATES } from './outcome_vocabularies.js';
 import {
     isSqliteAvailableSync,
     loadSqliteSync,
@@ -303,7 +303,7 @@ export const CONSUMPTION_STATES = ['consumed', 'partially-consumed', 'rejected-w
 export type Consumption = (typeof CONSUMPTION_STATES)[number];
 
 /**
- * The six terminal states as a runtime array.
+ * The run terminal states as a runtime array.
  *
  * Re-export of `RUN_TERMINAL_STATES` from `outcome_vocabularies.ts`. It used to
  * be a second literal list here, guarded by two type-level assertions that
@@ -316,6 +316,12 @@ export type Consumption = (typeof CONSUMPTION_STATES)[number];
  *
  * The name is kept because it is exported and pinned by
  * `tests/scripts/runtime_journal.test.ts:205,207`.
+ *
+ * Growing this list does NOT move {@link JOURNAL_SCHEMA_VERSION}: that covers
+ * tables and columns and a mismatch discards the store, while a widened value
+ * domain changes neither. The domain carries its own version in the registry
+ * (`RUN_TERMINAL_VOCABULARY_VERSION`), and the read path tolerates a value it
+ * does not know rather than trusting the column — see `toEvent`.
  */
 export const TERMINAL_STATES = RUN_TERMINAL_STATES;
 
@@ -1019,7 +1025,7 @@ export function recordEvent(h: JournalHandle, input: RecordEventInput): JournalE
         !(TERMINAL_STATES as readonly string[]).includes(input.terminal_state)
     ) {
         throw new JournalContractError(
-            `terminal_state ${JSON.stringify(input.terminal_state)} is not one of the six.`,
+            `terminal_state ${JSON.stringify(input.terminal_state)} is not in the run vocabulary.`,
         );
     }
     if (
@@ -1105,7 +1111,8 @@ function toEvent(r: Record<string, unknown>): JournalEvent {
         worktree_id: String(r['worktree_id']),
         at: String(r['at']),
         capability: String(r['capability']),
-        terminal_state: (r['terminal_state'] as TerminalState | null) ?? null,
+        // Tolerant, not a cast: a value this build cannot place reads as null.
+        terminal_state: readRunTerminalState(r['terminal_state']),
         return_ref: (r['return_ref'] as string | null) ?? null,
         verification_ref: (r['verification_ref'] as string | null) ?? null,
         consumption: (r['consumption'] as Consumption | null) ?? null,

package/src/scripts/_lib/semantic_noop.ts

@@ -0,0 +1,167 @@
+/**
+ * The semantic no-op gate — `road-to-harness-promotion-bridge` step 7.4.
+ *
+ * > *Reject semantic no-ops. A no-op detector plus a minimum
+ * > material-improvement threshold. The master kept the cooldown and lineage
+ * > from the same attack and dropped both gates.*
+ * > verify: **a paraphrase-only candidate is refused before the cascade.**
+ *
+ * ## "Before the cascade" — what that resolves to in this tree
+ *
+ * There is no artefact named "cascade" here; the evaluation cascade is the
+ * lifecycle spine, `proposed -> diagnostic-evaluated -> selection-evaluated ->
+ * …`. So "before the cascade" means: while the candidate is still `proposed`,
+ * before the first transition and before anything expensive runs.
+ * {@link screenSemanticNoOps} is that stage, and it is SYNCHRONOUS for the same
+ * reason `screenNearDuplicates` is — a synchronous function cannot await a
+ * network call, so the zero-model-call property follows from the signature
+ * rather than from a promise the body has to keep.
+ *
+ * ## Two gates, because the step asks for two
+ *
+ * 1. **The no-op detector.** {@link isSemanticNoOp} — a candidate whose text is
+ *    a paraphrase of what it replaces. Measured with `shingleOverlap`, the same
+ *    primitive `curator_ops`'s near-duplicate screen and `lint_originality` use.
+ * 2. **The minimum material-improvement threshold.** A candidate that is not a
+ *    paraphrase can still be a rounding error;
+ *    {@link MIN_MATERIAL_IMPROVEMENT_PERCENT} is the floor its measured delta
+ *    must clear.
+ *
+ * Both are needed and neither implies the other: a total rewrite that changes
+ * nothing measurable passes (1) and fails (2); a one-word change with a large
+ * measured delta passes (2) and fails (1). Shipping one of the two is what the
+ * master did.
+ */
+import { NEAR_DUPLICATE_THRESHOLD } from './curator_ops.js';
+import { shingleOverlap } from './shingle_similarity.js';
+
+/**
+ * Containment-overlap percent at which a candidate is a paraphrase of what it
+ * replaces.
+ *
+ * **Measured bound, stated rather than left for a reader to discover.**
+ * `shingleOverlap` uses 8-word shingles, so ONE substitution breaks eight
+ * shingles. On a one-sentence candidate (~10 shingles) that is already a
+ * 45-point drop and no paraphrase can reach 70 %; on rule-body-sized text
+ * (~60 words, 56 shingles) the same edit measures 85.7 %. The detector is
+ * therefore meaningful for the corpus it will see — rule and skill bodies — and
+ * weak for one-liners. `revisit-if` candidates turn out to be short.
+ *
+ * Pinned EQUAL to {@link NEAR_DUPLICATE_THRESHOLD} rather than given its own
+ * number, and the equality is the argument: both questions are "is this text
+ * substantially the text we already have", measured on the same primitive, and
+ * two independently-tuned constants for one question is how they drift. If one
+ * moves, the reason has to cover both.
+ */
+export const PARAPHRASE_OVERLAP_THRESHOLD = NEAR_DUPLICATE_THRESHOLD;
+
+/**
+ * The smallest measured improvement that counts as material, in percentage
+ * points.
+ *
+ * A STATED default, not a measured optimum — the honest label this repository
+ * uses for a number nobody has derived. `revisit-if` a real promotion is refused
+ * for a delta a human calls material, or admitted for one a human calls noise.
+ * It is deliberately small: the gate exists to reject ZERO, not to set a bar for
+ * ambition.
+ */
+export const MIN_MATERIAL_IMPROVEMENT_PERCENT = 1;
+
+export interface NoOpVerdict {
+    readonly isNoOp: boolean;
+    /** Why, in one clause. Empty when it is not a no-op. */
+    readonly reason: string;
+    readonly overlapPercent: number;
+    /** Literal 0. This stage is deterministic; a model call here would be a defect. */
+    readonly modelCalls: 0;
+}
+
+/**
+ * Is this candidate a semantic no-op against the text it replaces?
+ *
+ * Two ways to be one, and the second is the one a paraphrase detector alone
+ * misses: the text barely moved, or the text moved and the measured effect did
+ * not.
+ */
+export function isSemanticNoOp(
+    baselineText: string,
+    candidateText: string,
+    deltaPercent: number,
+    overlapThreshold: number = PARAPHRASE_OVERLAP_THRESHOLD,
+    minDelta: number = MIN_MATERIAL_IMPROVEMENT_PERCENT,
+): NoOpVerdict {
+    const overlapPercent = shingleOverlap(baselineText, candidateText);
+    if (overlapPercent >= overlapThreshold) {
+        return {
+            isNoOp: true,
+            reason:
+                `paraphrase-only: ${String(overlapPercent)}% shingle overlap with the text it replaces ` +
+                `(threshold ${String(overlapThreshold)}%)`,
+            overlapPercent,
+            modelCalls: 0,
+        };
+    }
+    if (deltaPercent < minDelta) {
+        return {
+            isNoOp: true,
+            reason:
+                `no material improvement: measured delta ${String(deltaPercent)} pp is below the ` +
+                `${String(minDelta)} pp floor`,
+            overlapPercent,
+            modelCalls: 0,
+        };
+    }
+    return { isNoOp: false, reason: '', overlapPercent, modelCalls: 0 };
+}
+
+export class SemanticNoOpError extends Error {
+    readonly candidateId: string;
+    constructor(candidateId: string, reason: string) {
+        super(
+            `candidate '${candidateId}' is a semantic no-op and is refused before the cascade: ${reason}. ` +
+                'Evaluating it would spend trials to measure nothing, and promoting it would grow the ' +
+                'estate by an artefact that says what the estate already says.',
+        );
+        this.name = 'SemanticNoOpError';
+        this.candidateId = candidateId;
+    }
+}
+
+/** @throws {SemanticNoOpError} when the candidate is a no-op. */
+export function assertNotSemanticNoOp(candidateId: string, verdict: NoOpVerdict): void {
+    if (verdict.isNoOp) {
+        throw new SemanticNoOpError(candidateId, verdict.reason);
+    }
+}
+
+export interface NoOpScreenInput {
+    readonly id: string;
+    readonly baselineText: string;
+    readonly candidateText: string;
+    readonly deltaPercent: number;
+}
+
+export interface NoOpScreenResult {
+    readonly admitted: readonly string[];
+    readonly refused: readonly { readonly id: string; readonly reason: string }[];
+    /** Literal 0 — the whole point of a pre-stage is that it is cheaper than what follows. */
+    readonly modelCalls: 0;
+}
+
+/**
+ * The pre-stage: refuse no-ops while every candidate is still `proposed`.
+ *
+ * Synchronous, and it takes TEXT rather than records on purpose — it must be
+ * callable before a candidate has any evaluation results attached, which is the
+ * whole meaning of "before the cascade".
+ */
+export function screenSemanticNoOps(candidates: readonly NoOpScreenInput[]): NoOpScreenResult {
+    const admitted: string[] = [];
+    const refused: { id: string; reason: string }[] = [];
+    for (const c of candidates) {
+        const verdict = isSemanticNoOp(c.baselineText, c.candidateText, c.deltaPercent);
+        if (verdict.isNoOp) refused.push({ id: c.id, reason: verdict.reason });
+        else admitted.push(c.id);
+    }
+    return { admitted, refused, modelCalls: 0 };
+}