fullstack-gates 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# fullstack-gates
+
+Проверки, которые **отказываются**, а не пропускают. Обычные файлы на вход, код возврата на выход,
+**ноль зависимостей** — только `node:fs`, `node:path` и рантайм Bun.
+
+```bash
+bun add -d fullstack-gates
+```
+
+```jsonc
+// package.json
+"scripts": {
+  "check:pins":     "stack-gate pins",
+  "check:priority": "stack-gate priority",
+  "check:debt":     "stack-gate debt",
+  "check":          "bun run lint && bun run type-check && bun run check:pins && bun run check:priority",
+  "ac":             "stack-gate ac"
+}
+```
+
+## Правило, из которого следует всё остальное
+
+**Пропущенная проверка выглядит ровно как пройденная.** Поэтому здесь нет ни одного гейта, который
+молча зеленеет, когда ему нечего проверять: пустой каталог критериев — отказ, пустой список
+манифестов — отказ, опечатка в имени гейта — отказ. Зелёный прогон обязан означать, что что-то было
+проверено, а не что проверять было нечего.
+
+## Гейты
+
+| `stack-gate …` | Что проверяет | Почему это не ловит ничто другое |
+|---|---|---|
+| `pins` | в объявлениях зависимостей нет `"latest"` / `"*"` | пока цел локфайл, плавающее объявление МОЛЧИТ; просыпается на `bun update` — когда никто уже не связывает поломку с объявлением полугодовой давности |
+| `ac` | критерии приёмки доказаны прогоном, галочки переписаны по факту | галочка, поставленная рукой, — обещание, а не отчёт |
+| `priority` | объявления приоритета в спеке действительны | опечатка `heigh` при молчаливом умолчании даёт `normal` — противоположное написанному, без признаков |
+| `next-slice` | какой слайс следующий: покрытие, провод, адреса, конфликты | очередь, названная человеком, называет удобное, а не следующее |
+| `wiring` | проводка экрана: мёртвый проп, дубль `data-testid`, эндпоинт без вызывающего | юнит и интеграция зовут сервер напрямую, оракул разметки согласен с прототипом по построению — провод не смотрит никто |
+| `write-path` | у каждого пишущего эндпоинта есть вызывающий в клиенте | кнопка, которая рапортует об успехе и ничего не делает, проходит все остальные уровни |
+| `proto` | извлечённая вёрстка не пересекает границу слоя представления | фикстура прототипа, ставшая ключом сущности, снимается потом переписыванием четырёх слоёв разом |
+| `proto-ids` | идентификаторы из прототипа не стали ключами | то же, но про адресацию |
+| `debt` | сознательно не сделанное названо и счётно | «пока не делаем», записанное комментарием в коде, выглядит взвешенным — и потому дыру никто не ищет |
+| `preflight` | условия уровня выполнены до его запуска | уровень, чьи условия не выполнены, обязан ПАДАТЬ и говорить, что запустить |
+
+`stack-gate` без аргументов печатает список; неизвестное имя — отказ с кодом 2, а не тихий пропуск.
+
+## Что гейт считает корнем репы
+
+Текущий каталог, если в нём есть `package.json`. Поэтому зовите их из корня — так же, как `bun run`.
+
+## Раскладка, которую предполагают гейты
+
+Часть проверок читает конкретные места: `docs/usecases/<пакет>/<слайс>.md` (критерии приёмки),
+`packages/*` и `apps/*` (манифесты), `apps/<любое>/src/client` (клиент). Раскладка описана в
+[плагине `fullstack`](https://github.com/itquick-aihub/fullstack-plugin) — он же ставит эти скрипты
+в репу и объясняет, что где живёт. Гейт, которому нечего проверять, скажет об этом и вернёт 1.
+
+## Лицензия
+
+MIT.

package/bin/stack-gate.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env bun
+/**
+ * `stack-gate <гейт>` — единая точка входа во все гейты пакета.
+ *
+ * Зачем диспетчер, а не по `bin` на файл. Двенадцать имён вроде `check-pins` и `ac` в общем
+ * `node_modules/.bin` — это двенадцать шансов столкнуться с чужим пакетом, и столкновение молчаливое:
+ * побеждает тот, кто установился последним, а `bun run check` продолжает печатать «зелено». Одно
+ * специфичное имя занимает одну ячейку и конфликтует заметно.
+ *
+ * Второе: путь до скрипта перестаёт быть частью продукта. Раскладка внутри пакета — наше дело, и
+ * менять её можно, не трогая `package.json` в каждой репе.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const ГЕЙТЫ: Record<string, string> = {
+  pins: "check-pins.ts",
+  priority: "check-priority.ts",
+  debt: "check-debt.ts",
+  wiring: "check-screen-wiring.ts",
+  proto: "check-prototype-boundary.ts",
+  "proto-ids": "check-proto-ids.ts",
+  "write-path": "check-write-path.ts",
+  "next-slice": "next-slice.ts",
+  ac: "ac.ts",
+  preflight: "preflight.ts",
+};
+
+const [имя, ...остальные] = process.argv.slice(2);
+
+if (!имя || имя === "--help" || имя === "-h") {
+  console.log("stack-gate <гейт> [аргументы]\n\nГейты:");
+  for (const k of Object.keys(ГЕЙТЫ)) console.log(`  ${k}`);
+  console.log("\nПример: stack-gate pins · stack-gate ac --no-tests");
+  process.exit(имя ? 0 : 2);
+}
+
+const файл = ГЕЙТЫ[имя];
+if (!файл) {
+  console.error(
+    `stack-gate: гейта «${имя}» нет. Доступны: ${Object.keys(ГЕЙТЫ).join(", ")}.\n` +
+      "Опечатка в имени не должна выглядеть как пройденная проверка, поэтому это отказ, а не пропуск."
+  );
+  process.exit(2);
+}
+
+const путь = join(import.meta.dir, "..", "scripts", файл);
+if (!existsSync(путь)) {
+  console.error(`stack-gate: файл гейта не найден: ${путь}. Пакет установлен не полностью.`);
+  process.exit(2);
+}
+
+/**
+ * Дочерний процесс, а не `import`: гейты — самостоятельные программы, которые общаются кодом
+ * возврата и пишут в stdout. `import` склеил бы их состояние и проглотил `process.exit`.
+ * `cwd` НЕ подменяется: гейт определяет корень репы по нему, и это должен быть каталог вызова.
+ */
+const proc = Bun.spawnSync(["bun", "run", путь, ...остальные], {
+  stdio: ["inherit", "inherit", "inherit"],
+  cwd: process.cwd(),
+  env: process.env,
+});
+process.exit(proc.exitCode ?? 1);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "fullstack-gates",
+  "version": "0.1.0",
+  "description": "Verification gates for a Bun + Elysia + Drizzle + Turborepo modular monolith: pinned dependency declarations, acceptance-criteria coverage, work queue, screen wiring, prototype boundary, declared debt. Plain files in, exit code out — no dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "stack-gate": "bin/stack-gate.ts"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "keywords": [
+    "bun",
+    "monorepo",
+    "ci",
+    "gates",
+    "acceptance-criteria",
+    "traceability",
+    "dependency-pinning",
+    "elysia",
+    "drizzle",
+    "turborepo"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itquick-aihub/fullstack-plugin.git",
+    "directory": "packages/fullstack-gates"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/ac.ts

@@ -0,0 +1,494 @@
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+
+/**
+ * `bun run ac` — acceptance coverage.
+ *
+ * The rule this enforces: **a checkbox is a REPORT, not a promise.** Nobody ticks an acceptance
+ * criterion by hand; a criterion is ticked because something proved it, and this script is what
+ * looks. That is the whole point — a hand-ticked list is a lie within a week, and we have the scars.
+ *
+ * How it works:
+ *   1. Use cases live in `docs/usecases/<package>/<slice>.md` — one file per module. They are the "what"
+ *      (the analyst's layer, and the first thing written, often before the package exists); the code
+ *      is the "how". Keeping them in `docs/` means a use case has a home from the day it is thought
+ *      of, not from the day someone creates a package for it.
+ *   2. Every acceptance criterion has a stable id: `- [ ] \`AC-GW-01.3\` …`.
+ *   3. A test claims a criterion by naming it: `it("AC-GW-01.3 — 403 when …")`. No registry, no
+ *      decorator — the id in the title IS the link.
+ *   4. Some criteria CANNOT be proven by a test — behaviour of an external system, a limit enforced by
+ *      a real proxy. Those carry `live:YYYY-MM-DD@<commit>` — evidence from a stand
+ *      run, with a date, so it visibly goes stale instead of quietly becoming folklore.
+ *
+ * Gates:
+ *   - a test naming an unknown id           → error (typo protection)
+ *   - a criterion nobody proves             → listed as a hole; `--strict` makes it an exit code
+ *
+ * Usage: bun run ac [--strict] [--no-tests]   (`--no-tests` reuses the last junit run)
+ */
+import { $ } from "bun";
+
+import { applyIntegrationEnv } from "./integration-env";
+
+/**
+ * Корень РЕПЫ, а не скрипта. Файл — КОПИЯ, живущая в `scripts/` репы, но тот же исходник иногда
+ * зовут прямо из ассетов плагина; тогда `import.meta.url` указывает мимо репы, и отчёт пишется не
+ * туда. Поэтому первично `cwd` (там, где есть `package.json`), а путь от файла — запасной.
+ */
+const ROOT = existsSync(join(process.cwd(), "package.json"))
+  ? resolve(process.cwd())
+  : new URL("..", import.meta.url).pathname.replace(/\/$/, "");
+const USECASES_DIR = join(ROOT, "docs/usecases");
+const JUNIT = "/tmp/ac-junit.xml";
+const STALE_DAYS = 60;
+
+const strict = Bun.argv.includes("--strict");
+const skipTests = Bun.argv.includes("--no-tests");
+
+/**
+ * Source files are `docs/usecases/<пакет>/<слайс>.md` — mirroring the code's own two levels
+ * (`packages/<пакет>/…/features/<слайс>`), so "where does this use case live" has the same answer as
+ * "where does this code live". They are the ones carrying `feature:` frontmatter; the generated index
+ * (`index.md`) is recognized by NOT having it, so prose sitting alongside can never be mistaken for
+ * a module.
+ */
+async function findUsecaseFiles(dir: string = USECASES_DIR, out: string[] = []): Promise<string[]> {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await findUsecaseFiles(path, out);
+    } else if (entry.name.endsWith(".md") && /^feature:\s*\S/m.test(await Bun.file(path).text())) {
+      out.push(path);
+    }
+  }
+  return out;
+}
+
+/** The package a use-case file belongs to = its directory, exactly as in `packages/`. */
+function packageOf(path: string): string {
+  const rel = relative(USECASES_DIR, path);
+  return rel.includes("/") ? rel.split("/")[0]! : "—";
+}
+
+interface Criterion {
+  id: string;
+  text: string;
+  live: string | null; // "2026-07-14@402b5b9"
+  e2e: string | null; // "2026-08-14@a1b2c3d" — см. parseEvidence()
+  line: number;
+}
+interface UseCaseFile {
+  path: string;
+  feature: string;
+  title: string;
+  criteria: Criterion[];
+  /** UC-заголовки, за которыми сразу идёт `### AC` — то есть без описания. */
+  bodiless: string[];
+  lines: string[];
+}
+
+const AC_LINE = /^\s*[-*]\s*\[[ xX]\]\s*`(AC-[A-Z]+-\d+\.\d+)`\s*(.*)$/;
+
+/** Полный идентификатор критерия. Ровно он и достаётся из имени теста. */
+const AC_ID = /AC-[A-Z]+-\d+\.\d+/g;
+
+/**
+ * ОБРЕЗАННАЯ ССЫЛКА В ИМЕНИ ТЕСТА — брак, который иначе не виден никак.
+ *
+ * Тест, названный `AC-IMP-06.1/.2`, связывается ТОЛЬКО с первым идентификатором: `/.2` не полный
+ * ID, и раннер его не видит. Тест зелёный, автор уверен, что доказал оба, а второй критерий тихо
+ * остаётся непокрытым — и обнаруживается это счётчиком покрытия через недели, если вообще.
+ *
+ * Случилось дважды на одном слайсе за один день (`AC-IMP-04.5`, затем `AC-IMP-06.2`), причём
+ * второй раз — уже зная про первый. Значит это не невнимательность, а форма, к которой тянет:
+ * два соседних критерия проверяются одним сценарием, и объединить их в имени кажется естественным.
+ *
+ * Ловится тем, ЧТО ИДЁТ СРАЗУ ЗА идентификатором: голое число после `/`, `,`, `и` или тире — это
+ * попытка сослаться на соседний критерий, не назвав его. Полный второй ID (`AC-…-06.2`) под правило
+ * не подпадает и подпадать не должен: два ID в имени — законный способ доказать оба одним тестом.
+ */
+export function danglingRefs(name: string): string[] {
+  const найдено: string[] = [];
+  for (const m of name.matchAll(AC_ID)) {
+    const хвост = name.slice((m.index ?? 0) + m[0].length);
+    const обрезок = /^\s*(?:[/,]|и\s|[-–—])\s*\.?\d+/.exec(хвост);
+    if (обрезок) найдено.push(`${m[0]}${обрезок[0]}`);
+  }
+  return найдено;
+}
+const LIVE = /·\s*live:(\d{4}-\d{2}-\d{2})@([0-9a-f]{7,40})/;
+const E2E = /`e2e:(\d{4}-\d{2}-\d{2}@[0-9a-f]{7,40})`/;
+const UC_HEADING = /^## (UC-[A-Z]+-\d+)\./;
+
+/**
+ * Доказательство критерия одной строкой. Два вида, оба с датой и коммитом, чтобы видимо протухать:
+ *   `live:ГГГГ-ММ-ДД@<коммит>` — прогон на стенде, поведение внешней системы. Формат — БЕЗ обратных
+ *      кавычек, `· live:...` (так задокументировано в `traceability.md` и так его пишут руками);
+ *      меняем его тут неохотно, чтобы не разойтись с уже написанным.
+ *   `e2e:ГГГГ-ММ-ДД@<коммит>`  — браузерный прогон уровня 4, ставится ТОЛЬКО прогоном (`claimAc` из
+ *      `e2e/support.ts`), поэтому вложен в обратные кавычки: так его пишет `claimAc`, и так же он
+ *      отличим от произвольного текста критерия, где обратные кавычки — обычное дело (например,
+ *      `` `draft` ``).
+ *
+ * Второй заведён потому, что уровень 4 не идёт через `bun test` и в junit не попадает: браузерный
+ * тест физически не мог отметить ни одного критерия, и UI-часть требований оставалась недоказуемой
+ * тем гейтом, который для этого и существует.
+ *
+ * Дата без коммита доказательством НЕ считается: дату проставить легко, а коммит привязывает
+ * доказательство к состоянию кода.
+ *
+ * Номера строки в результате нет: функция не знает своей позиции в файле — это знает вызывающий.
+ */
+export function parseEvidence(line: string): Omit<Criterion, "line"> | null {
+  const m = line.match(AC_LINE);
+  if (!m) return null;
+  const [, id, tail] = m;
+  const rest = tail ?? "";
+  return {
+    id: id!,
+    // Сначала снимаем маркер e2e (его `claimAc` мог дописать без «·» перед ним — иначе он попал бы
+    // в текст критерия), потом отрезаем всё после первого «·» (старые тесты/live-евиденс).
+    text: rest.replace(E2E, "").split("·")[0]!.trim(),
+    live: rest.match(LIVE) ? `${rest.match(LIVE)![1]}@${rest.match(LIVE)![2]}` : null,
+    e2e: rest.match(E2E)?.[1] ?? null,
+  };
+}
+
+function parse(path: string, source: string): UseCaseFile {
+  const lines = source.split("\n");
+  const feature = source.match(/^feature:\s*(.+)$/m)?.[1]?.trim() ?? "?";
+  const title = source.match(/^title:\s*(.+)$/m)?.[1]?.trim() ?? path;
+  const criteria: Criterion[] = [];
+  const bodiless: string[] = [];
+
+  lines.forEach((line, i) => {
+    // A use case whose heading is followed straight by its AC list is not a use case — it is a
+    // checklist wearing one. That is exactly how the prose (Цель/Актёр/Поток/Ошибки/Полиморфизм)
+    // was once lost in a refactor without a single test going red: nothing was watching.
+    const uc = line.match(UC_HEADING);
+    if (uc) {
+      const next = lines.slice(i + 1).find((l) => l.trim().length > 0) ?? "";
+      if (next.startsWith("###")) bodiless.push(uc[1]!);
+      return;
+    }
+
+    const c = parseEvidence(line);
+    if (!c) return;
+    criteria.push({ ...c, line: i });
+  });
+
+  return { path, feature, title, criteria, bodiless, lines };
+}
+
+// ── what the tests proved ───────────────────────────────────────────────────────────────────────
+interface Proof {
+  passing: Map<string, string[]>; // AC id → test names that pass
+  failing: Map<string, string[]>;
+  unknownIds: Set<string>;
+  /** Имена тестов с обрезанной ссылкой на соседний критерий. Брак, а не предупреждение. */
+  dangling: Map<string, string[]>;
+}
+
+async function runTests(knownIds: Set<string>): Promise<Proof> {
+  if (!skipTests) {
+    // Окружение интеграции — из одного места, а не из строки в `package.json`. Вызов здесь, а не на
+    // верхнем уровне файла: при `--no-tests` уровень it не нужен и трогать окружение незачем.
+    applyIntegrationEnv();
+    // Уровень it — часть доказательства, а не опция. Без TEST_DATABASE_URL интеграционные тесты не
+    // регистрируются вовсе: они не падают и не «скипаются» — их просто нет в отчёте. Генератор тогда
+    // МОЛЧА снимает галочки с критериев, которые доказываются только интеграцией (так и случилось с
+    // AC-IDP-03.2), и отчёт приёмки начинает зависеть от того, из какой оболочки его позвали.
+    // Пропущенный уровень — не пройденный: отказываемся переписывать документы, а не врём тихо.
+    if (!process.env.TEST_DATABASE_URL) {
+      console.error(
+        "❌ TEST_DATABASE_URL пуст — уровень it не побежит, и галочки, которые он доказывает,\n" +
+          "   снялись бы молча. Умолчание живёт в scripts/integration-env.ts; пустым оно бывает\n" +
+          "   только если его СТЁРЛИ явно (`TEST_DATABASE_URL= bun run ac`).\n" +
+          "   Нужен только отчёт по прошлому прогону — `bun run scripts/ac.ts --no-tests`."
+      );
+      process.exit(1);
+    }
+    // Bun's junit reporter gives us names + status; a non-zero exit just means some test failed,
+    // which is itself a result we want to report rather than crash on.
+    await $`bun test --reporter=junit --reporter-outfile=${JUNIT}`.cwd(ROOT).nothrow().quiet();
+  }
+
+  const xml = await Bun.file(JUNIT).text();
+  const passing = new Map<string, string[]>();
+  const failing = new Map<string, string[]>();
+  const unknownIds = new Set<string>();
+  const dangling = new Map<string, string[]>();
+
+  // A testcase is either self-closing (`<testcase … />`) or wraps a <failure>. The lazy attr match
+  // BEFORE the branch is what keeps a self-closing tag from swallowing the next dozen testcases —
+  // the greedy version silently merged them and reported zero coverage.
+  for (const match of xml.matchAll(/<testcase\b([^>]*?)(\/>|>([\s\S]*?)<\/testcase>)/g)) {
+    const attrs = match[1] ?? "";
+    const body = match[3] ?? "";
+    const name = attrs.match(/name="([^"]*)"/)?.[1] ?? "";
+    const failed = /<failure|<error/.test(body);
+
+    const обрезки = danglingRefs(name);
+    if (обрезки.length > 0) dangling.set(name, обрезки);
+
+    for (const id of name.match(AC_ID) ?? []) {
+      if (!knownIds.has(id)) {
+        unknownIds.add(id);
+        continue;
+      }
+      const bucket = failed ? failing : passing;
+      bucket.set(id, [...(bucket.get(id) ?? []), name]);
+    }
+  }
+  return { passing, failing, unknownIds, dangling };
+}
+
+// ── rewrite the checkboxes: the file becomes a report of what is true right now ──────────────────
+function daysSince(date: string): number {
+  return Math.floor((Date.now() - new Date(date).getTime()) / 86_400_000);
+}
+
+/**
+ * Критерий доказан: ни один тест не падает, и есть хоть одно доказательство — прошедший тест либо
+ * стендовая/браузерная отметка. Единственное место для этой проверки: раньше она была продублирована
+ * в трёх независимых местах (`render()`, подсчёт дырок, подсчёт покрытия для index.md), и правка
+ * добавления `e2e` требовала синхронно менять все три — следующий вид доказательства забыли бы
+ * повторить хотя бы в одном, и критерий оказался бы доказан в одном отчёте и не доказан в другом.
+ */
+function isProven(passes: number, fails: number, live: string | null, e2e: string | null): boolean {
+  return fails === 0 && (passes > 0 || live !== null || e2e !== null);
+}
+
+function render(
+  file: UseCaseFile,
+  proof: Proof
+): { text: string; covered: number; stale: string[] } {
+  const lines = [...file.lines];
+  const stale: string[] = [];
+  let covered = 0;
+
+  for (const c of file.criteria) {
+    const passes = proof.passing.get(c.id)?.length ?? 0;
+    const fails = proof.failing.get(c.id)?.length ?? 0;
+
+    const evidence: string[] = [];
+    if (passes) evidence.push(`тесты: ${passes}`);
+    if (fails) evidence.push(`🔴 падает: ${fails}`);
+    let stales = false;
+    if (c.live) {
+      const age = daysSince(c.live.split("@")[0]!);
+      evidence.push(`live:${c.live}${age > STALE_DAYS ? ` ⚠️ ${age}д` : ""}`);
+      if (age > STALE_DAYS) stales = true;
+    }
+    if (c.e2e) {
+      // Без инлайн-предупреждения после кавычки: `claimAc` ищет `` `e2e:...` `` регуляркой, которая
+      // требует, чтобы маркер был ПОСЛЕДНИМ на строке — текст после закрывающей кавычки сломал бы
+      // поиск на следующем прогоне claimAc. Протухание видно в сводном списке ниже.
+      const age = daysSince(c.e2e.split("@")[0]!);
+      evidence.push(`\`e2e:${c.e2e}\``);
+      if (age > STALE_DAYS) stales = true;
+    }
+    if (stales) stale.push(c.id);
+
+    const proven = isProven(passes, fails, c.live, c.e2e);
+    if (proven) covered++;
+
+    const tail = evidence.length ? ` · ${evidence.join(" · ")}` : "";
+    lines[c.line] = `- [${proven ? "x" : " "}] \`${c.id}\` ${c.text}${tail}`;
+  }
+
+  return { text: lines.join("\n"), covered, stale };
+}
+
+// ── main ────────────────────────────────────────────────────────────────────────────────────────
+// Под гвардом: `ac.test.ts` импортирует `parseEvidence` из этого же модуля, а импорт ES-модуля
+// выполняет его тело целиком. Без гварда юнит-тест на чистую функцию попутно гонял бы весь отчёт —
+// писал файлы в docs/usecases и падал по process.exit(1) из-за отсутствующего TEST_DATABASE_URL.
+if (import.meta.main) {
+  const files = (await findUsecaseFiles()).sort();
+  const parsed = await Promise.all(files.map(async (p) => parse(p, await Bun.file(p).text())));
+  const knownIds = new Set(parsed.flatMap((f) => f.criteria.map((c) => c.id)));
+
+  console.log(`📄 use-case файлов: ${parsed.length}, критериев: ${knownIds.size}`);
+
+  // Пустой каталог — это ПРОВАЛ, а не «покрыто 0/0».
+  //
+  // `new-project.sh` штатно велит удалить демо-пакет вместе с его use cases. После этого прогон
+  // печатал «✅ покрыто 0/0» и выходил нулём: `verify:full` зелёный, доказано ничего. Это ровно тот
+  // молчаливый успех, против которого написан весь этот скрипт, — только на уровень выше.
+  if (knownIds.size === 0) {
+    console.error(
+      "\n❌ ни одного критерия приёмки: в " +
+        relative(ROOT, USECASES_DIR) +
+        " нет ни одного use case с `feature:` в шапке.\n" +
+        "   Зелёный прогон без критериев ничего не доказывает. Опиши первый use case — или, если\n" +
+        "   проект действительно ещё без них, убери `ac` из `verify:full`, а не делай его пустым."
+    );
+    process.exit(1);
+  }
+  const proof = await runTests(knownIds);
+
+  const rows: string[] = [];
+  let totalCovered = 0;
+  let totalCriteria = 0;
+  const holes: string[] = [];
+  const staleAll: string[] = [];
+
+  for (const file of parsed) {
+    const { text, covered, stale } = render(file, proof);
+    await Bun.write(file.path, text);
+
+    totalCovered += covered;
+    totalCriteria += file.criteria.length;
+    staleAll.push(...stale);
+
+    for (const c of file.criteria) {
+      const proven = isProven(
+        proof.passing.get(c.id)?.length ?? 0,
+        proof.failing.get(c.id)?.length ?? 0,
+        c.live,
+        c.e2e
+      );
+      if (!proven) holes.push(`${c.id} — ${c.text}`);
+    }
+
+    const pct = file.criteria.length ? Math.round((covered / file.criteria.length) * 100) : 0;
+    rows.push(
+      `| ${packageOf(file.path)} | ${file.feature} | ${file.title} | ${covered}/${file.criteria.length} | ${pct}% | \`${relative(ROOT, file.path)}\` |`
+    );
+  }
+
+  // The aggregate: an index, not a second copy of the prose. The module file stays the source.
+  const report = `# Покрытие критериев приёмки
+
+> Сгенерировано \`bun run ac\` — не правь руками. Критерии живут в \`docs/usecases/<пакет>/<слайс>.md\`;
+> галочку ставит прогон, а не человек.
+
+**Итог: ${totalCovered}/${totalCriteria} (${Math.round((totalCovered / Math.max(1, totalCriteria)) * 100)}%)** · непокрыто: ${holes.length}
+
+| Пакет | Ф | Слайс | Покрыто | % | Файл |
+|---|---|---|---|---|---|
+${rows.join("\n")}
+
+Какие именно критерии не покрыты — видно там же, где они живут: незакрытый \`- [ ]\` в файле модуля.
+Второй копии списка здесь нет намеренно: свод — это оглавление, а не вторая копия прозы.
+${staleAll.length ? `\n## ⚠️ Протухшие доказательства (\`live\`/\`e2e\`, > ${STALE_DAYS} дней)\n\n${staleAll.map((s) => `- ${s}`).join("\n")}\n\nЭто НЕ дубль галочек: отметка \`live:\`/\`e2e:\` протухает молча, и единственное место, где это видно сразу, — здесь.\n` : ""}`;
+
+  await Bun.write(join(ROOT, "docs/acceptance.md"), report);
+
+  // docs/usecases/index.md — СВОД: оглавление по модулям + покрытие. Проза живёт в файле модуля,
+  // здесь только указатель, иначе появится вторая копия правды, и она разойдётся с первой.
+  /**
+   * Ссылка ставится, ТОЛЬКО если цель существует.
+   *
+   * Генератор печатал указатели на `engineering/traceability.md`, `glossary.md` и
+   * `engineering/decisions.md` — документы, которых он не создаёт и которых в ПРОДУКТЕ может не быть
+   * вовсе. Сверка артефактов ловила их битой ссылкой, и чинили это правкой СГЕНЕРИРОВАННОГО файла,
+   * то есть заводили копию генератора, расходящуюся с ним на первом же прогоне. Генератор,
+   * ссылающийся в пустоту, чинится в генераторе.
+   */
+  const есть = (rel: string) => existsSync(join(ROOT, "docs", rel));
+  const ссылка = (rel: string, подпись: string) =>
+    есть(rel) ? `[\`../${rel}\`](../${rel})` : `\`${подпись}\` (в этой репе нет)`;
+
+  const механика = есть("engineering/traceability.md")
+    ? ` (механика — ${ссылка("engineering/traceability.md", "")})`
+    : "";
+  const инварианты = есть("engineering/decisions.md")
+    ? `это \`NFR-*\` в ${ссылка("engineering/decisions.md", "")}, а не отдельный список: второй копии не будет`
+    : "каждый UC называет их сам: единого реестра `NFR-*` в этой репе нет";
+
+  const index = `# Use Cases
+
+> Сгенерировано \`bun run ac\`. **Не правь этот файл** — правь \`docs/usecases/<пакет>/<слайс>.md\`.
+> Раскладка повторяет код: пакет → слайс.
+> Галочку ставит прогон, а не человек: она отчёт, а не обещание${механика}.
+>
+> Термины и действующие лица → ${ссылка("glossary.md", "docs/glossary.md")}. Инварианты, которые держат
+> ВСЕ UC (deny-default, идемпотентность, актор из принципала, серверные списки, аудит) — ${инварианты}.
+
+**Покрытие: ${totalCovered}/${totalCriteria} (${Math.round((totalCovered / Math.max(1, totalCriteria)) * 100)}%)** · подробности: [\`../acceptance.md\`](../acceptance.md)
+
+| Пакет | Ф | Слайс | Критерии | Покрыто | Файл |
+|---|---|---|---|---|---|
+${parsed
+  .slice()
+  .sort(
+    (a, b) =>
+      packageOf(a.path).localeCompare(packageOf(b.path)) ||
+      Number(a.feature.replace(/\D/g, "")) - Number(b.feature.replace(/\D/g, ""))
+  )
+  .map((f) => {
+    const covered = f.criteria.filter((c) =>
+      isProven(
+        proof.passing.get(c.id)?.length ?? 0,
+        proof.failing.get(c.id)?.length ?? 0,
+        c.live,
+        c.e2e
+      )
+    ).length;
+    const rel = relative(USECASES_DIR, f.path);
+    return `| \`${packageOf(f.path)}\` | ${f.feature} | ${f.title} | ${f.criteria.length} | ${covered} | [\`${rel}\`](${rel}) |`;
+  })
+  .join("\n")}
+
+## Как читать
+
+- **Критерий без галочки** — это либо реальная дырка, либо тест, который его доказывает, но не
+  сослался на ID. Скрипт не умеет их различать и не притворяется, что умеет.
+- **\`live:ДАТА@коммит\`** — доказано на стенде: то, что тестом не докажешь (поведение внешней системы,
+  лимит через настоящий прокси). Протухает через 60 дней, иначе стало бы лазейкой.
+- **\`e2e:ДАТА@коммит\`** — доказано браузерным прогоном уровня 4 (\`claimAc\` в \`apps/web/e2e/support.ts\`):
+  уровень 4 не идёт через \`bun test\` и в junit не попадает, поэтому ставит отметку сам прогон. Тоже
+  протухает через 60 дней.
+`;
+  await Bun.write(join(USECASES_DIR, "index.md"), index);
+
+  console.log(`✅ покрыто ${totalCovered}/${totalCriteria}; отчёт → docs/acceptance.md`);
+
+  // A UC that is only a checkbox list has lost the thing a use case IS: цель, актёр, поток, ошибки,
+  // полиморфизм. It once happened silently during a refactor, and no test could see it — so the
+  // engine looks.
+  const bodiless = parsed.flatMap((f) =>
+    f.bodiless.map((uc) => `${uc} (${relative(ROOT, f.path)})`)
+  );
+  if (bodiless.length > 0) {
+    console.warn(
+      `\n⚠️  use case без описания (сразу «### AC»): ${bodiless.join(", ")}\n` +
+        "   Критерии — это ещё не use case. Допиши Цель · Актёр · Поток · Ошибки · Полиморфизм."
+    );
+    if (strict) process.exit(1);
+  }
+  /**
+   * Отказ идёт ПЕРВЫМ, раньше остальных: обрезанная ссылка — причина, а «непокрытый критерий» ниже
+   * — её следствие, и увидев только следствие, чинить будут не то.
+   */
+  if (proof.dangling.size > 0) {
+    console.error(
+      `\n❌ имя теста ссылается на соседний критерий, не называя его (${proof.dangling.size}):`
+    );
+    for (const [name, обрезки] of proof.dangling) {
+      console.error(`   ${name}`);
+      console.error(`     обрезано: ${обрезки.join(", ")}`);
+    }
+    console.error(
+      "\n   Раннер связывает тест ТОЛЬКО с полными идентификаторами: `AC-XXX-01.1/.2` доказывает\n" +
+        "   первый критерий и молча оставляет второй непокрытым — при зелёном тесте.\n" +
+        "   Почини одним из двух: раздели на два теста (обычно верно — у критериев разные утверждения)\n" +
+        "   либо назови оба полностью: `AC-XXX-01.1 и AC-XXX-01.2 — …`."
+    );
+    process.exit(1);
+  }
+
+  if (proof.unknownIds.size > 0) {
+    console.error(
+      `\n❌ тесты ссылаются на несуществующие критерии: ${[...proof.unknownIds].join(", ")}`
+    );
+    process.exit(1);
+  }
+  if (strict && holes.length > 0) {
+    console.error(`\n❌ непокрытых критериев: ${holes.length}`);
+    process.exit(1);
+  }
+}