@shahimat/harness 0.1.0 → 0.3.0

package/README.md

@@ -25,6 +25,16 @@ npx -y @shahimat/harness@<version> <команда> --root .
 - `harness adapters sync` — файлы под Claude Code и Codex из
   `AGENTS.md` и `.agents/`: `CLAUDE.md`, копии skills, субагенты,
   выключенная memory агента.
+- `harness expect init` — каркас ожиданий в проекте: конфиг vitest,
+  пример файла с бюджетом, npm-скрипты, `.gitignore`.
+- `harness expect report | lint | judge [--apply]` — ожидания в форме
+  vitest (`expectations/*.expect.ts`): дерево со статусами, проверка
+  заголовков, пакетная смысловая проверка судьёй-агентом с кэшем
+  вердиктов. Помощники для проверок — `@shahimat/harness/expect`
+  (нужен vitest в проекте): `crit` / `warn` / `note` / `budget`,
+  `expectAtMost` (info при > 90% порога), зонды по репозиторию,
+  `judged`, проверка JSON Schema (`expectSchema`, `dataFiles`,
+  `frontmatters`).
 - `harness index build | check --raw-base <url>` — индекс
   `prompts/index.yml` репозитория промптов.
 
@@ -34,7 +44,7 @@ npx -y @shahimat/harness@<version> <команда> --root .
 ## `context/harness.yml`
 
 ```yaml
-version: 0.1.0
+version: 0.3.0
 adapters: [claude-code, codex]
 checks:
   changelog:

package/dist/checks/context-index.js

@@ -229,36 +229,55 @@ class Collector {
                     this.report(manifest, `index_layers: dir «${String(dir)}» — нужен путь внутри проекта`);
                     continue;
                 }
+                const format = (isRecord(item) ? item['format'] : undefined) ?? 'md';
+                if (format !== 'md' && format !== 'yml') {
+                    this.report(manifest, `index_layers: format «${String(format)}» — md или yml`);
+                    continue;
+                }
                 const taken = layers.find((l) => l.section === section);
                 if (taken !== undefined) {
                     this.report(manifest, `index_layers: section «${section}» уже объявлена в ${taken.manifest}`);
                     continue;
                 }
-                layers.push({ section, dir: dir.replace(/\/+$/, ''), manifest });
+                layers.push({ section, dir: dir.replace(/\/+$/, ''), format, manifest });
             }
         }
         return layers;
     }
     /**
-     * Файл слоя модуля — markdown с frontmatter `id`, `namespace`; строка
-     * индекса — первый `# …`. `id` = путь внутри слоя без `.md`, `/` → `-`.
+     * Файл слоя модуля: `md` — frontmatter `id`, `namespace`, строка индекса —
+     * первый `# …`; `yml` — поля `id`, `namespace`, `summary`. `id` = путь
+     * внутри слоя без расширения, `/` → `-`.
      */
     async collectLayer(layer) {
-        for (const file of await listFiles(this.root, layer.dir, '.md')) {
+        const ext = layer.format === 'md' ? '.md' : '.yml';
+        for (const file of await listFiles(this.root, layer.dir, ext)) {
             let data;
-            const text = await readFile(path.join(this.root, file), 'utf8');
-            try {
-                data = parseFrontmatter(text);
-            }
-            catch (error) {
-                this.report(file, `невалидный frontmatter: ${error.message.split('\n')[0]}`);
-                continue;
+            let title;
+            if (layer.format === 'yml') {
+                data = await this.readYaml(file);
+                if (data === null)
+                    continue;
+                title = this.oneLine(file, data, 'summary');
             }
-            if (data === null) {
-                this.report(file, 'нет frontmatter (id, namespace)');
-                continue;
+            else {
+                const text = await readFile(path.join(this.root, file), 'utf8');
+                try {
+                    data = parseFrontmatter(text);
+                }
+                catch (error) {
+                    this.report(file, `невалидный frontmatter: ${error.message.split('\n')[0]}`);
+                    continue;
+                }
+                if (data === null) {
+                    this.report(file, 'нет frontmatter (id, namespace)');
+                    continue;
+                }
+                title = firstHeading(text);
+                if (title === null)
+                    this.report(file, 'нет заголовка «# …» (одна строка для индекса)');
             }
-            const expected = file.slice(layer.dir.length + 1, -'.md'.length).split('/').join('-');
+            const expected = file.slice(layer.dir.length + 1, -ext.length).split('/').join('-');
             const id = data['id'];
             if (typeof id !== 'string' || id === '') {
                 this.report(file, 'нет поля id');
@@ -267,9 +286,6 @@ class Collector {
             if (id !== expected)
                 this.report(file, `id «${id}» не совпадает с путём «${expected}»`);
             const ns = this.checkNamespace(file, data);
-            const title = firstHeading(text);
-            if (title === null)
-                this.report(file, 'нет заголовка «# …» (одна строка для индекса)');
             if (ns === null)
                 continue;
             const sections = this.namespace(ns).layers;

package/dist/cli.js

@@ -4,6 +4,7 @@ import { runAdapters } from './commands/adapters.js';
 import { runChangelog } from './commands/changelog.js';
 import { runCheck } from './commands/check.js';
 import { runContext } from './commands/context.js';
+import { runExpect } from './commands/expect.js';
 import { runIndex } from './commands/prompt-index.js';
 import { UsageError } from './diagnostics.js';
 const USAGE = `Использование:
@@ -11,6 +12,7 @@ const USAGE = `Использование:
   harness adapters sync [--root <dir>]
   harness changelog lint [--root <dir>]
   harness context index [--root <dir>]
+  harness expect init | report | lint | judge [--apply] [--root <dir>]
   harness index build --raw-base <url> [--root <dir>] [--out <file>]
   harness index check --raw-base <url> [--root <dir>]
 
@@ -23,6 +25,7 @@ export async function main(argv, now = new Date()) {
             root: { type: 'string', default: '.' },
             out: { type: 'string' },
             'raw-base': { type: 'string' },
+            apply: { type: 'boolean' },
             help: { type: 'boolean', short: 'h' },
         },
     });
@@ -35,6 +38,8 @@ export async function main(argv, now = new Date()) {
         args.out = values.out;
     if (values['raw-base'] !== undefined)
         args.rawBase = values['raw-base'];
+    if (values.apply === true)
+        args.apply = true;
     const [group, command] = positionals;
     switch (group) {
         case 'adapters':
@@ -45,6 +50,8 @@ export async function main(argv, now = new Date()) {
             return runChangelog(command, args);
         case 'context':
             return runContext(command, args);
+        case 'expect':
+            return runExpect(command, args);
         case 'index':
             return runIndex(command, args);
         default:

package/dist/commands/expect.d.ts

@@ -0,0 +1,3 @@
+import type { CommandArgs } from './types.ts';
+export declare const EXPECT_CONFIG = "expectations/vitest.config.ts";
+export declare function runExpect(command: string | undefined, args: CommandArgs): Promise<number>;

package/dist/commands/expect.js

@@ -0,0 +1,303 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { UsageError } from '../diagnostics.js';
+import { applyAnswers, applyLintAnswer, planBatches, renderBatch, renderLintBatch } from '../expect/batch.js';
+import { readEvidence, shaOf } from '../expect/evidence.js';
+import { COLLECT_ENV, idOf } from '../expect/judge.js';
+import { BUDGET_TITLE } from '../expect/levels.js';
+import { lintTitles } from '../expect/lint.js';
+import { loadVerdicts, saveVerdicts, VERDICTS_PATH } from '../expect/verdicts.js';
+export const EXPECT_CONFIG = 'expectations/vitest.config.ts';
+const JUDGE_DIR = 'expectations/.judge';
+/** Запускает vitest проекта на файлах ожиданий и возвращает результаты. */
+function runVitest(root, env = {}) {
+    if (!existsSync(path.join(root, EXPECT_CONFIG)))
+        throw new UsageError(`нет ${EXPECT_CONFIG}`);
+    const require = createRequire(path.join(root, 'package.json'));
+    let vitestPkg;
+    try {
+        vitestPkg = require.resolve('vitest/package.json');
+    }
+    catch {
+        throw new UsageError('vitest не установлен в проекте: npm i -D vitest');
+    }
+    const bin = JSON.parse(readFileSync(vitestPkg, 'utf8')).bin['vitest'] ?? '';
+    const out = path.join(tmpdir(), `harness-expect-${process.pid}-${Date.now()}.json`);
+    spawnSync(process.execPath, [path.join(path.dirname(vitestPkg), bin), 'run', '--root', root, '--config', EXPECT_CONFIG, '--reporter=json', `--outputFile=${out}`], { cwd: root, env: { ...process.env, ...env, HARNESS_EXPECT_ROOT: root }, stdio: ['ignore', 'ignore', 'inherit'] });
+    if (!existsSync(out))
+        throw new Error('vitest не записал отчёт');
+    const data = JSON.parse(readFileSync(out, 'utf8'));
+    rmSync(out, { force: true });
+    return data.testResults.flatMap((file) => file.assertionResults.map((a) => {
+        const result = {
+            file: path.relative(root, file.name).split(path.sep).join('/'),
+            path: a.ancestorTitles,
+            title: a.title,
+            status: a.status,
+            message: (a.failureMessages[0] ?? '').split('\n')[0] ?? '',
+            // Обычный it() без обёртки — crit: формальная проверка по умолчанию.
+            level: a.meta?.level ?? 'crit',
+            notes: a.meta?.notes ?? [],
+        };
+        if (a.meta?.budget !== undefined)
+            result.budget = a.meta.budget;
+        return result;
+    }));
+}
+const fullName = (t) => [...t.path, t.title].join(' > ');
+function byFile(results) {
+    const files = new Map();
+    for (const r of results)
+        files.set(r.file, [...(files.get(r.file) ?? []), r]);
+    return files;
+}
+const titlesSha = (tests) => shaOf(tests.map(fullName).sort().join('\n'));
+const isPending = (t) => t.status === 'failed' && t.message.includes('нет свежего вердикта');
+async function report(args) {
+    const all = runVitest(args.root);
+    const store = await loadVerdicts();
+    const titleIssues = lintTitles(all.filter((r) => r.title !== BUDGET_TITLE).map((r) => ({ file: r.file, path: r.path, title: r.title })));
+    let blocked = false;
+    let total = { tests: 0, crit: 0, warn: 0, info: 0, pending: 0 };
+    for (const [file, tests] of byFile(all)) {
+        const budget = tests.find((t) => t.title === BUDGET_TITLE)?.budget ?? { crit: 0, warn: 0 };
+        const items = tests.filter((t) => t.title !== BUDGET_TITLE);
+        const count = { crit: 0, warn: 0, info: 0, pending: 0 };
+        console.log(file);
+        let prev = [];
+        for (const t of items) {
+            t.path.forEach((p, i) => {
+                if (prev[i] !== p)
+                    console.log(`${'  '.repeat(i + 1)}${p}`);
+            });
+            prev = t.path;
+            const pad = '  '.repeat(t.path.length + 1);
+            if (isPending(t)) {
+                count.pending++;
+                console.log(`${pad}? ${t.title}  — нужен вердикт судьи`);
+            }
+            else if (t.status === 'failed') {
+                count[t.level === 'warn' ? 'warn' : 'crit']++;
+                console.log(`${pad}${t.level === 'warn' ? '⚠' : '✗'} ${t.title}  — ${t.message}`);
+            }
+            else {
+                console.log(`${pad}${t.status === 'todo' ? '○' : t.status === 'passed' ? '✓' : '-'} ${t.title}`);
+            }
+            for (const n of t.notes)
+                console.log(`${pad}  ℹ ${n}`);
+            count.info += t.notes.length;
+        }
+        for (const d of titleIssues.filter((i) => i.title.file === file)) {
+            count[d.level]++;
+            console.log(`  ${d.level === 'crit' ? '✗' : '⚠'} заголовок «${d.title.title}» — ${d.message}`);
+        }
+        const lint = store.lint[file];
+        if (lint === undefined || lint.titles !== titlesSha(items)) {
+            count.pending++;
+            console.log('  ? смысловая проверка заголовков устарела — harness expect judge');
+        }
+        else {
+            const name = new Map(items.map((t) => [idOf(fullName(t)), t.title]));
+            for (const c of lint.contradictions)
+                console.log(`  ⚠ противоречие: «${name.get(c.a)}» ↔ «${name.get(c.b)}» — ${c.reason}`);
+            for (const u of lint.unmeasurable)
+                console.log(`  ⚠ неизмеримо: «${name.get(u.id)}» — ${u.reason}`);
+            count.warn += lint.contradictions.length + lint.unmeasurable.length;
+        }
+        const over = count.crit > budget.crit || count.warn > budget.warn || count.pending > 0;
+        blocked ||= over;
+        console.log(`  ${over ? '✗' : '✓'} crit ${count.crit}/${budget.crit} · warn ${count.warn}/${budget.warn} · info ${count.info}` +
+            (count.pending > 0 ? ` · ? ${count.pending} без вердикта` : ''));
+        total = {
+            tests: total.tests + items.length,
+            crit: total.crit + count.crit,
+            warn: total.warn + count.warn,
+            info: total.info + count.info,
+            pending: total.pending + count.pending,
+        };
+    }
+    console.log(`\nожиданий ${total.tests}: crit ${total.crit} · warn ${total.warn} · info ${total.info} · ? ${total.pending} — ${blocked ? 'бюджет превышен' : 'в бюджете'}`);
+    return blocked ? 1 : 0;
+}
+async function lint(args) {
+    const titles = runVitest(args.root)
+        .filter((r) => r.title !== BUDGET_TITLE)
+        .map((r) => ({ file: r.file, path: r.path, title: r.title }));
+    const diags = lintTitles(titles);
+    for (const d of diags)
+        console.error(`${d.level} ${d.title.file}: «${d.title.title}» — ${d.message}`);
+    console.log(diags.length === 0 ? `expect lint: ok (${titles.length})` : `expect lint: нарушений ${diags.length}`);
+    return diags.length === 0 ? 0 : 1;
+}
+async function judgePrepare(args) {
+    const dir = path.join(args.root, JUDGE_DIR);
+    await rm(dir, { recursive: true, force: true });
+    const pendingDir = path.join(dir, 'pending');
+    const results = runVitest(args.root, { [COLLECT_ENV]: pendingDir });
+    const items = [];
+    if (existsSync(pendingDir)) {
+        for (const f of (await readdir(pendingDir)).sort())
+            items.push(JSON.parse(await readFile(path.join(pendingDir, f), 'utf8')));
+        await rm(pendingDir, { recursive: true, force: true });
+    }
+    const plan = { batches: [], lint: [] };
+    for (const [i, batch] of planBatches(items).entries()) {
+        const task = `${JUDGE_DIR}/batch-${i + 1}.md`;
+        const answer = `${JUDGE_DIR}/batch-${i + 1}.answer.json`;
+        await mkdir(dir, { recursive: true });
+        await writeFile(path.join(args.root, task), renderBatch(batch, answer), 'utf8');
+        plan.batches.push({ task, answer, items: batch.items });
+    }
+    const store = await loadVerdicts();
+    for (const [file, all] of byFile(results)) {
+        const tests = all.filter((t) => t.title !== BUDGET_TITLE);
+        const sha = titlesSha(tests);
+        if (store.lint[file]?.titles === sha)
+            continue;
+        const n = plan.lint.length + 1;
+        const task = `${JUDGE_DIR}/lint-${n}.md`;
+        const answer = `${JUDGE_DIR}/lint-${n}.answer.json`;
+        const titles = tests.map((t) => ({ id: idOf(fullName(t)), title: fullName(t) }));
+        await mkdir(dir, { recursive: true });
+        await writeFile(path.join(args.root, task), renderLintBatch(file, titles, answer), 'utf8');
+        plan.lint.push({ task, answer, file, titles: sha, ids: titles.map((t) => t.id) });
+    }
+    if (plan.batches.length === 0 && plan.lint.length === 0) {
+        console.log('expect judge: всё свежее, судья не нужен');
+        return 0;
+    }
+    await writeFile(path.join(dir, 'plan.json'), JSON.stringify(plan, null, 2), 'utf8');
+    console.log(`expect judge: вопросов ${items.length} в пакетах ${plan.batches.length}, проверок заголовков ${plan.lint.length}`);
+    for (const t of [...plan.batches, ...plan.lint])
+        console.log(`  ${t.task} → ${t.answer}`);
+    console.log('Каждый файл — задание судье (субагенту), ответ — в указанный JSON. Затем: harness expect judge --apply');
+    return 1;
+}
+async function judgeApply(args) {
+    const planFile = path.join(args.root, JUDGE_DIR, 'plan.json');
+    if (!existsSync(planFile))
+        throw new UsageError('нет плана: сначала harness expect judge');
+    const plan = JSON.parse(await readFile(planFile, 'utf8'));
+    const store = await loadVerdicts();
+    const rejected = [];
+    const readJson = async (rel) => {
+        try {
+            return JSON.parse(await readFile(path.join(args.root, rel), 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    for (const b of plan.batches) {
+        const answers = await readJson(b.answer);
+        if (answers === undefined) {
+            rejected.push(`${b.answer}: нет ответа`);
+            continue;
+        }
+        const texts = new Map();
+        for (const ref of new Set(b.items.flatMap((i) => i.evidence.map((e) => e.ref))))
+            texts.set(ref, await readEvidence(ref));
+        const result = applyAnswers(b.items, answers, texts, args.now);
+        Object.assign(store.verdicts, result.accepted);
+        for (const r of result.rejected)
+            rejected.push(`${b.answer}: ${r.id} — ${r.reason}`);
+    }
+    for (const l of plan.lint) {
+        const answer = await readJson(l.answer);
+        const { verdict, error } = applyLintAnswer(l.titles, new Set(l.ids), answer, args.now);
+        if (verdict === null)
+            rejected.push(`${l.answer}: ${error ?? 'нет ответа'}`);
+        else
+            store.lint[l.file] = verdict;
+    }
+    await saveVerdicts(store);
+    for (const r of rejected)
+        console.error(r);
+    if (rejected.length > 0) {
+        console.error(`expect judge --apply: отклонено ${rejected.length}; принятое сохранено в ${VERDICTS_PATH}`);
+        return 1;
+    }
+    await rm(path.join(args.root, JUDGE_DIR), { recursive: true, force: true });
+    console.log(`expect judge --apply: вердикты сохранены в ${VERDICTS_PATH}`);
+    return 0;
+}
+const INIT_CONFIG = `import { defineConfig } from 'vitest/config';
+
+// Ожидания: заголовки crit/warn — для человека, проверки — класс Check ниже в файле.
+// Отчёт: npm run expect. Вердикты судьи: npm run expect:judge → expect:apply.
+export default defineConfig({
+  test: {
+    include: ['expectations/**/*.expect.ts'],
+    testTimeout: 30_000,
+  },
+});
+`;
+const initExample = (name) => `import { describe, it } from 'vitest';
+import { budget } from '@shahimat/harness/expect';
+
+budget({ crit: 0, warn: 0 });
+
+describe('${name}', () => {
+  it.todo('первое ожидание: одно утверждение до 200 символов, да/нет или число');
+});
+
+// ─────────────────────────────── проверки ───────────────────────────────
+
+class Check {}
+void Check;
+`;
+/** Каркас ожиданий в проекте; существующие файлы не трогаются. */
+async function init(args) {
+    const done = [];
+    const put = async (rel, content) => {
+        const abs = path.join(args.root, rel);
+        if (existsSync(abs))
+            return;
+        await mkdir(path.dirname(abs), { recursive: true });
+        await writeFile(abs, content, 'utf8');
+        done.push(`создан ${rel}`);
+    };
+    const name = path.basename(args.root);
+    await put(EXPECT_CONFIG, INIT_CONFIG);
+    await put(`expectations/${name}.expect.ts`, initExample(name));
+    const gitignore = path.join(args.root, '.gitignore');
+    const ignored = existsSync(gitignore) ? await readFile(gitignore, 'utf8') : '';
+    if (!ignored.split('\n').includes(`${JUDGE_DIR}/`)) {
+        await writeFile(gitignore, `${ignored}${ignored === '' || ignored.endsWith('\n') ? '' : '\n'}${JUDGE_DIR}/\n`, 'utf8');
+        done.push(`.gitignore: ${JUDGE_DIR}/`);
+    }
+    const pkgFile = path.join(args.root, 'package.json');
+    if (existsSync(pkgFile)) {
+        const pkg = JSON.parse(await readFile(pkgFile, 'utf8'));
+        const scripts = { expect: 'harness expect report --root .', 'expect:judge': 'harness expect judge --root .', 'expect:apply': 'harness expect judge --apply --root .' };
+        const added = Object.entries(scripts).filter(([k]) => pkg.scripts?.[k] === undefined);
+        if (added.length > 0) {
+            pkg.scripts = { ...pkg.scripts, ...Object.fromEntries(added) };
+            await writeFile(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+            done.push(`package.json: скрипты ${added.map(([k]) => k).join(', ')}`);
+        }
+    }
+    for (const line of done)
+        console.log(line);
+    console.log(done.length === 0 ? 'expect init: всё уже на месте' : 'expect init: готово');
+    console.log('Зависимости: npm i -D vitest @shahimat/harness [@shahimat/expectations]');
+    return 0;
+}
+export async function runExpect(command, args) {
+    switch (command) {
+        case 'init':
+            return init(args);
+        case 'report':
+            return report(args);
+        case 'lint':
+            return lint(args);
+        case 'judge':
+            return args.apply === true ? judgeApply(args) : judgePrepare(args);
+        default:
+            throw new UsageError(`неизвестная команда: expect ${command ?? ''}`.trimEnd());
+    }
+}

package/dist/commands/types.d.ts

@@ -3,6 +3,8 @@ export interface CommandArgs {
     root: string;
     out?: string;
     rawBase?: string;
+    /** `expect judge --apply`: применить ответы судьи. */
+    apply?: boolean;
     /** Текущий момент; подменяется в тестах. */
     now: Date;
 }

package/dist/expect/batch.d.ts

@@ -0,0 +1,44 @@
+import type { PendingItem } from './judge.ts';
+import type { LintVerdict, Verdict } from './verdicts.ts';
+export interface BatchLimits {
+    maxItems: number;
+    maxBytes: number;
+}
+export declare const DEFAULT_LIMITS: BatchLimits;
+export interface Batch {
+    items: PendingItem[];
+    /** Уникальные доказательства пакета — судья читает каждое один раз. */
+    refs: string[];
+    bytes: number;
+}
+/**
+ * Пакеты для судьи: ожидания с одинаковыми доказательствами — вместе,
+ * группы складываются в пакеты до лимита вопросов и объёма доказательств.
+ */
+export declare function planBatches(items: PendingItem[], limits?: BatchLimits): Batch[];
+export declare function renderBatch(batch: Batch, answerFile: string): string;
+export interface Answer {
+    id: string;
+    verdict: boolean;
+    ref: string;
+    quote: string;
+    reason: string;
+}
+export interface ApplyResult {
+    accepted: Record<string, Verdict>;
+    rejected: {
+        id: string;
+        reason: string;
+    }[];
+}
+/** Проверяет ответы судьи; цитата должна дословно встречаться в доказательстве. */
+export declare function applyAnswers(items: PendingItem[], answers: unknown, evidenceText: Map<string, string>, now: Date): ApplyResult;
+/** Смысловая проверка заголовков одного файла ожиданий — один проход. */
+export declare function renderLintBatch(file: string, titles: {
+    id: string;
+    title: string;
+}[], answerFile: string): string;
+export declare function applyLintAnswer(titlesSha: string, ids: Set<string>, answer: unknown, now: Date): {
+    verdict: LintVerdict | null;
+    error: string | null;
+};

package/dist/expect/batch.js

@@ -0,0 +1,157 @@
+import { containsQuote } from './evidence.js';
+export const DEFAULT_LIMITS = { maxItems: 25, maxBytes: 80_000 };
+/**
+ * Пакеты для судьи: ожидания с одинаковыми доказательствами — вместе,
+ * группы складываются в пакеты до лимита вопросов и объёма доказательств.
+ */
+export function planBatches(items, limits = DEFAULT_LIMITS) {
+    const groups = new Map();
+    for (const item of [...items].sort((a, b) => (a.id < b.id ? -1 : 1))) {
+        const key = item.evidence.map((e) => e.ref).sort().join('\n');
+        groups.set(key, [...(groups.get(key) ?? []), item]);
+    }
+    const batches = [];
+    const sizes = new Map();
+    const bytesOf = (refs) => [...refs].reduce((n, r) => n + (sizes.get(r) ?? 0), 0);
+    let current = { items: [], refs: new Set() };
+    const flush = () => {
+        if (current.items.length === 0)
+            return;
+        batches.push({ items: current.items, refs: [...current.refs].sort(), bytes: bytesOf(current.refs) });
+        current = { items: [], refs: new Set() };
+    };
+    for (const group of groups.values()) {
+        for (const e of group[0]?.evidence ?? [])
+            sizes.set(e.ref, e.bytes);
+        for (const item of group) {
+            const refs = new Set([...current.refs, ...item.evidence.map((e) => e.ref)]);
+            if (current.items.length >= limits.maxItems || (current.items.length > 0 && bytesOf(refs) > limits.maxBytes))
+                flush();
+            current.items.push(item);
+            for (const e of item.evidence)
+                current.refs.add(e.ref);
+        }
+    }
+    flush();
+    return batches;
+}
+export function renderBatch(batch, answerFile) {
+    const lines = [
+        '# Пакет для судьи ожиданий',
+        '',
+        'Ты — судья. Прочитай доказательства (каждое один раз) и ответь на',
+        'каждый вопрос: выполнено ли утверждение — да (true) или нет (false).',
+        'Отвечай только по доказательствам, без догадок.',
+        '',
+        'Для каждого ответа — дословная цитата (8–300 символов) из одного',
+        'доказательства и его ссылка (`ref`). Цитата проверяется программно:',
+        'не найдена в тексте — ответ отклоняется. Для «нет» — цитата того, что',
+        'противоречит или ближе всего к утверждению, и причина.',
+        '',
+        `Ответ — JSON-массив в файл \`${answerFile}\`:`,
+        '',
+        '```json',
+        '[{"id": "<id>", "verdict": true, "ref": "<ref>", "quote": "<цитата>", "reason": "<одна строка>"}]',
+        '```',
+        '',
+        '## Доказательства',
+        '',
+        'Ссылка `path#Заголовок` — раздел markdown с этим заголовком.',
+        '',
+        ...batch.refs.map((r) => `- \`${r}\``),
+        '',
+        '## Вопросы',
+        '',
+    ];
+    for (const item of batch.items) {
+        lines.push(`- \`${item.id}\` — ${item.question.split(' > ').join(' → ')}`);
+        lines.push(`  доказательства: ${item.evidence.map((e) => `\`${e.ref}\``).join(', ')}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** Проверяет ответы судьи; цитата должна дословно встречаться в доказательстве. */
+export function applyAnswers(items, answers, evidenceText, now) {
+    const result = { accepted: {}, rejected: [] };
+    if (!Array.isArray(answers)) {
+        result.rejected.push({ id: '*', reason: 'ответ — не JSON-массив' });
+        return result;
+    }
+    const byId = new Map(items.map((i) => [i.id, i]));
+    for (const raw of answers) {
+        const id = String(raw.id ?? '');
+        const item = byId.get(id);
+        if (item === undefined) {
+            result.rejected.push({ id, reason: 'неизвестный id' });
+            continue;
+        }
+        if (typeof raw.verdict !== 'boolean') {
+            result.rejected.push({ id, reason: 'verdict — не true/false' });
+            continue;
+        }
+        const ref = String(raw.ref ?? '');
+        if (!item.evidence.some((e) => e.ref === ref)) {
+            result.rejected.push({ id, reason: `ref «${ref}» не из доказательств вопроса` });
+            continue;
+        }
+        const quote = String(raw.quote ?? '');
+        if (quote.length > 300 || !containsQuote(evidenceText.get(ref) ?? '', quote)) {
+            result.rejected.push({ id, reason: 'цитата не найдена в доказательстве дословно' });
+            continue;
+        }
+        result.accepted[id] = {
+            question: item.question,
+            evidence: Object.fromEntries(item.evidence.map((e) => [e.ref, e.sha])),
+            verdict: raw.verdict,
+            quote,
+            ref,
+            reason: String(raw.reason ?? ''),
+            at: now.toISOString().slice(0, 10),
+        };
+    }
+    for (const item of items) {
+        if (!(item.id in result.accepted) && !result.rejected.some((r) => r.id === item.id)) {
+            result.rejected.push({ id: item.id, reason: 'нет ответа' });
+        }
+    }
+    return result;
+}
+/** Смысловая проверка заголовков одного файла ожиданий — один проход. */
+export function renderLintBatch(file, titles, answerFile) {
+    return [
+        '# Проверка заголовков ожиданий',
+        '',
+        `Файл: \`${file}\`. Каждая строка — ожидание человека к реализации.`,
+        'Найди:',
+        '',
+        '1. Противоречия — пары ожиданий, которые не могут быть выполнены',
+        '   одновременно.',
+        '2. Неизмеримые — ожидания, на которые нельзя ответить «да/нет» или',
+        '   числом (размыто, оценочно, без порога).',
+        '',
+        'Ничего не нашёл — пустые массивы. Не выдумывай проблем.',
+        '',
+        `Ответ — JSON в файл \`${answerFile}\`:`,
+        '',
+        '```json',
+        '{"contradictions": [{"a": "<id>", "b": "<id>", "reason": "<строка>"}], "unmeasurable": [{"id": "<id>", "reason": "<строка>"}]}',
+        '```',
+        '',
+        '## Ожидания',
+        '',
+        ...titles.map((t) => `- \`${t.id}\` — ${t.title}`),
+        '',
+    ].join('\n');
+}
+export function applyLintAnswer(titlesSha, ids, answer, now) {
+    const a = answer;
+    if (a === null || typeof a !== 'object' || !Array.isArray(a.contradictions) || !Array.isArray(a.unmeasurable)) {
+        return { verdict: null, error: 'ответ — не {contradictions: [], unmeasurable: []}' };
+    }
+    const bad = [...a.contradictions.flatMap((c) => [c.a, c.b]), ...a.unmeasurable.map((u) => u.id)].filter((id) => !ids.has(id));
+    if (bad.length > 0)
+        return { verdict: null, error: `неизвестные id: ${bad.join(', ')}` };
+    return {
+        verdict: { titles: titlesSha, contradictions: a.contradictions, unmeasurable: a.unmeasurable, at: now.toISOString().slice(0, 10) },
+        error: null,
+    };
+}