agent-quality-kit 0.5.0 → 0.6.0

package/tool/commands/project.mjs

@@ -267,7 +267,13 @@ async function cmdStart(args) {
       if (declared.has(rec.slug)) continue;
       const v = triggerVerdict(rec, facts0);
       if (!v.applies) { skipped.push([rec.slug, v.why]); continue; }
-      const { cmd, noRecipe } = await installGate(rec.slug, man, facts0);
+      const { cmd, noRecipe, retired } = await installGate(rec.slug, man, facts0);
+      // Выведенная запись в пачку не идёт, но и молчать о ней нельзя: она попадает в тот же
+      // список пропущенного с названным преемником.
+      if (retired !== undefined) {
+        skipped.push([rec.slug, L.lifecycle.installDeprecated(rec.slug, retired || "—")]);
+        declared.add(rec.slug); continue;
+      }
       // Записи, которой нужен инструмент, а его на машине нет, здесь не место — но и вся
       // установка из-за неё останавливаться не должна. Причина называется вслух и попадает
       // в тот же список пропущенного, что и записи, не подошедшие по триггеру.

package/tool/i18n/en.mjs

@@ -15,6 +15,7 @@ export const en = {
     start: "no code yet: day-zero guards and the order of work",
     doctor: "check what is laid out and what is missing",
     doctorRun: "and also run the declared gates",
+    doctorSince: "the same, but show only what the diff against a ref introduced",
     add: "install a gate from the catalogue into the project",
     find: "is there already such a gate — matched by intent",
     why: "a bug slipped through — why did no guard catch it",
@@ -66,6 +67,10 @@ export const en = {
     totalTodo: (n) => `applicable but not installed ${n}`,
     totalSkip: (n) => `hidden ${n}`,
 
+    sinceHeading: (ref, n) => `narrowed to the diff against ${ref}: ${n} files touched`,
+    sinceBadRef: (ref) => `cannot compare against "${ref}": no such ref, or this is not a git repository`,
+    notScopable: "output carries no paths — cannot be narrowed by diff, left red",
+    outsideDiff: (n) => `findings exist, but outside the diff (${n})`,
     runHeading: "Running the declared gates",
     timeout: "did not finish within 5 minutes",
     exitCode: (code) => `exit ${code}`,
@@ -136,6 +141,18 @@ export const en = {
     none: "no recipe described",
   },
 
+  // Entry maturity. Computed from the entry's proof; it cannot be declared — see
+  // entryLifecycle in tool/lib/manifest.mjs.
+  lifecycle: {
+    stable: "proven by an incident from the journal",
+    experimental: "proof is not from the journal — the entry is provisional",
+    deprecated: "retired",
+    unknownReplacement: (v) => `superseded_by: ${v} — no such entry in the catalogue`,
+    noReplacement: "lifecycle: deprecated without superseded_by — no replacement is named",
+    notDeclarable: (v) => `lifecycle: ${v} cannot be declared — maturity is computed from the proof`,
+    unknown: (v) => `lifecycle: ${v} — no such state; only deprecated is declared`,
+    installDeprecated: (slug, by) => `entry ${slug} is retired, ${by} replaces it`,
+  },
   manifest: {
     noGatesBlock: "no gates: block in .aqk.yml",
     alreadyDeclared: "already declared",

package/tool/i18n/ru.mjs

@@ -16,6 +16,7 @@ export const ru = {
     start: "кода ещё нет: сторожа дня 0 и порядок работы",
     doctor: "проверить, что разложено и чего не хватает",
     doctorRun: "ещё и запустить объявленные гейты",
+    doctorSince: "то же, но показать только то, что внёс диф относительно ссылки",
     add: "поставить гейт из каталога в проект",
     find: "есть ли уже такой гейт — сверка по намерению",
     why: "поймал ошибку — почему её не поймал сторож",
@@ -67,6 +68,10 @@ export const ru = {
     totalTodo: (n) => `применимо но не поставлено ${n}`,
     totalSkip: (n) => `скрыто ${n}`,
 
+    sinceHeading: (ref, n) => `сужено до дифа относительно ${ref}: файлов затронуто ${n}`,
+    sinceBadRef: (ref) => `не могу сравнить с «${ref}»: такой ссылки нет или это не репозиторий git`,
+    notScopable: "вывод без путей — дифом не сужается, оставлен красным",
+    outsideDiff: (n) => `находки есть, но вне дифа (${n})`,
     runHeading: "Прогон объявленных гейтов",
     timeout: "не уложился в 5 минут",
     exitCode: (code) => `код ${code}`,
@@ -142,6 +147,19 @@ export const ru = {
     none: "рецепт не описан",
   },
 
+  // Зрелость записи каталога. Считается по доказательству; объявить её нельзя — см.
+  // entryLifecycle в tool/lib/manifest.mjs.
+  lifecycle: {
+    stable: "доказана шишкой из журнала",
+    experimental: "доказательство не из журнала — запись условная",
+    deprecated: "выведена из употребления",
+    unknownReplacement: (v) => `superseded_by: ${v} — такой записи в каталоге нет`,
+    noReplacement: "lifecycle: deprecated без superseded_by — не назван тот, кто заменяет",
+    notDeclarable: (v) => `lifecycle: ${v} объявлять нельзя — зрелость считается по доказательству`,
+    unknown: (v) => `lifecycle: ${v} — такого состояния нет; объявляется только deprecated`,
+    installDeprecated: (slug, by) =>
+      `запись ${slug} выведена из употребления, её заменяет ${by}`,
+  },
   manifest: {
     noGatesBlock: "в .aqk.yml нет блока gates:",
     alreadyDeclared: "уже объявлен",

package/tool/i18n/templates-en.mjs

@@ -11,17 +11,17 @@ const AGENTS_MD = `# AGENTS.md
 
 ## Hard rules
 
-- **A plan before code.** A non-trivial task starts with a plan a human approved in words.
-- **A red test before code.** First a check that fails, then the implementation.
-- **Three attempts maximum.** Not solved in three — stop and ask a human, not a fourth try.
-- **Secrets only in the environment.** Never in code, logs or commits.
-- **Only the files the task is about.** No fixing things "while we are here".
-- **Done = proven.** Name the arbiter: a test, a live run, a check against the source.
+- **A plan before code.** A non-trivial task starts with a plan a human approved in words.  <!-- aqk: human -->
+- **A red test before code.** First a check that fails, then the implementation.  <!-- aqk: human -->
+- **Three attempts maximum.** Not solved in three — stop and ask a human, not a fourth try.  <!-- aqk: human -->
+- **Secrets only in the environment.** Never in code, logs or commits.  <!-- aqk: secrets-not-in-code -->
+- **Only the files the task is about.** No fixing things "while we are here".  <!-- aqk: human -->
+- **Done = proven.** Name the arbiter: a test, a live run, a check against the source.  <!-- aqk: human -->
   "Looks like it works" is not done.
-- **Never swallow an error.** Either handled and logged, or re-raised.
-- **A fork in the road is a question for a human.** Departing from an agreed decision is not
+- **Never swallow an error.** Either handled and logged, or re-raised.  <!-- aqk: swallowed-error -->
+- **A fork in the road is a question for a human.** Departing from an agreed decision is not  <!-- aqk: human -->
   documented with a code comment.
-- **Report on your work with the kit with a command, not with words.** When you are done, run
+- **Report on your work with the kit with a command, not with words.** When you are done, run  <!-- aqk: human -->
   \`aqk report\`. It is assembled from an actual run: a summary from memory always picks the
   convenient parts and stays quiet about a gate standing on the weakest recipe.
 

package/tool/i18n/templates-ru.mjs

@@ -16,17 +16,17 @@ const AGENTS_MD = `# AGENTS.md
 
 ## Железные правила
 
-- **План до кода.** Нетривиальная задача начинается с плана, который человек одобрил словами.
-- **Красный тест до кода.** Сначала проверка, которая падает, потом реализация.
-- **Максимум 3 попытки.** Не решил за три — стоп и человеку, а не четвёртый заход.
-- **Секреты только в окружении.** Никогда в коде, логах и коммитах.
-- **Только файлы из задачи.** Заодно ничего не чиним.
-- **Готово = доказано.** Назови арбитра: тест, живой прогон, сверка с источником. «Выглядит
+- **План до кода.** Нетривиальная задача начинается с плана, который человек одобрил словами.  <!-- aqk: человек -->
+- **Красный тест до кода.** Сначала проверка, которая падает, потом реализация.  <!-- aqk: человек -->
+- **Максимум 3 попытки.** Не решил за три — стоп и человеку, а не четвёртый заход.  <!-- aqk: человек -->
+- **Секреты только в окружении.** Никогда в коде, логах и коммитах.  <!-- aqk: secrets-not-in-code -->
+- **Только файлы из задачи.** Заодно ничего не чиним.  <!-- aqk: человек -->
+- **Готово = доказано.** Назови арбитра: тест, живой прогон, сверка с источником. «Выглядит  <!-- aqk: человек -->
   рабочим» — не готово.
-- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.
-- **Развилка — вопрос человеку.** Отступление от принятого решения не оформляется комментарием
+- **Ошибку не глотать.** Либо обработана и залогирована, либо проброшена.  <!-- aqk: swallowed-error -->
+- **Развилка — вопрос человеку.** Отступление от принятого решения не оформляется комментарием  <!-- aqk: человек -->
   в коде.
-- **Отчёт о работе с комплектом — командой, а не словами.** Закончил — выполни \`aqk report\`.
+- **Отчёт о работе с комплектом — командой, а не словами.** Закончил — выполни \`aqk report\`.  <!-- aqk: человек -->
   Он собирается прогоном: пересказ по памяти всегда выбирает удобное и молчит о том, что гейт
   стоит на слабейшем рецепте.
 

package/tool/lib/manifest.mjs

@@ -86,6 +86,39 @@ function unknownKeys(man) {
   return Object.keys(man).filter((k) => !KNOWN_KEYS.includes(k));
 }
 
+// ЗРЕЛОСТЬ ЗАПИСИ. Каталог без зрелости — это список, в котором нельзя отличить проверенное от
+// свежего; при шестнадцати записях это держится на памяти, при чужих записях — уже нет.
+//
+// ПОЧЕМУ ВЫЧИСЛЯЕТСЯ, А НЕ ОБЪЯВЛЯЕТСЯ. Поле зрелости есть у всех троих соседей — `lifecycle`
+// у зондов Scorecard, `future`/`obsolete` у критериев значка OpenSSF — и у всех троих его
+// заполняет автор. Значение, которое написал автор, означает доверие к автору, а не факт: это
+// ровно тот способ, которым «зелёный» перестаёт что-либо значить. Здесь зрелость считается по
+// доказательству записи, и объявить её нельзя — попытка отклоняется приёмкой каталога.
+//
+// Исключение одно: `deprecated`. «Запись больше не ставят» из её собственных файлов не выводится
+// никак — это решение, а не факт. Цена решения — обязательная замена: запись, выведенная в
+// никуда, оставляет человека без ответа на вопрос «а что теперь».
+const LIFECYCLE_COMPUTED = ["stable", "experimental"];
+
+function entryLifecycle(rec) {
+  const declared = typeof rec?.lifecycle === "string" ? rec.lifecycle.trim() : "";
+  const supersededBy = typeof rec?.superseded_by === "string" ? rec.superseded_by.trim() : "";
+  // Тот же признак, которым каталог отделяет условную запись с первого дня: доказательство
+  // ссылается на журнал шишек — значит, запись родилась из настоящей поломки, а не из
+  // «это хорошая практика». Признак один на всю программу: разъехавшись, он дал бы приёмке
+  // и отчёту разные ответы про одну и ту же запись.
+  const proven = /incidents\//.test(String(rec?.proof || ""));
+  const state = declared === "deprecated" ? "deprecated" : proven ? "stable" : "experimental";
+  const why = L.lifecycle[state];
+
+  let problem = null;
+  if (declared === "deprecated" && !supersededBy) problem = L.lifecycle.noReplacement;
+  else if (LIFECYCLE_COMPUTED.includes(declared)) problem = L.lifecycle.notDeclarable(declared);
+  else if (declared && declared !== "deprecated") problem = L.lifecycle.unknown(declared);
+
+  return { state, why, supersededBy: supersededBy || null, problem };
+}
+
 async function readManifest() {
   const p = join(CWD, MANIFEST);
   if (!(await exists(p))) return null;
@@ -149,4 +182,7 @@ function manifestWithGate(text, slug, cmd) {
   return { text: out, why: null };
 }
 
-export { parseManifest, readManifest, assessLevel, manifestWithGate, unknownKeys, KNOWN_KEYS };
+export {
+  parseManifest, readManifest, assessLevel, manifestWithGate, unknownKeys, KNOWN_KEYS,
+  entryLifecycle,
+};

package/tool/lib/scope.mjs

@@ -0,0 +1,96 @@
+// tool/lib/scope.mjs — сужение вывода гейта до того, что внёс диф.
+//
+// ЗАЧЕМ. Первый прогон в живом проекте показывает долг, накопленный годами: на репозитории в
+// 36 тысяч файлов это тысячи находок. Человек видит стену красного, понимает, что разобрать её
+// нельзя, и выключает проверку целиком. Это причина номер один, по которой такие инструменты
+// снимают, — и три независимых проекта из нашего разбора умеют показывать только внесённое
+// (reviewdog, `--since` у ratchets, четыре режима шума у react-doctor).
+//
+// ПОЧЕМУ ФИЛЬТР ВЫВОДА, А НЕ СПИСОК ФАЙЛОВ ГЕЙТУ. Гейт — произвольная команда оболочки: у
+// каждого инструмента свой способ принять список файлов, а у переносимых проверок его нет
+// вовсе. Фильтр вывода работает с любым гейтом, ничего не требуя от записи каталога.
+//
+// ЧЕГО ЭТОТ ФИЛЬТР НЕ УМЕЕТ И НЕ ДЕЛАЕТ ВИД, ЧТО УМЕЕТ. Он сужает до ФАЙЛА, а не до строки.
+// Находка в файле, который диф трогал, показывается целиком, даже если она в нетронутой строке.
+// Сужение до строки требует разбора формата каждого инструмента — то есть ровно той привязки
+// к инструменту, которой у нас нет.
+
+import { spawnSync } from "node:child_process";
+
+// Один и тот же файл приезжает в трёх видах: `src/a.py`, `./src/a.py` и `src\a.py` на Windows.
+function normPath(p) {
+  return String(p).replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+
+// Цвет снимается ДО поиска путей. Родные инструменты печатают путь внутри
+// escape-последовательности, и сравнение видит не «src/a.py», а обрывок с управляющими
+// символами. На живом проекте это уже стоило одной починки, которая выглядела работающей:
+// вывод «сократился» с 5597 строк до 5505, то есть не сократился.
+const ANSI = new RegExp(String.fromCharCode(27) + "\\[[0-9;]*[a-zA-Z]", "g");
+
+// Кандидат в путь: слово с расширением, начинающимся с БУКВЫ. Требование буквы отсекает номера
+// версий — «0.5.0» иначе читается как файл с расширением «0», и строка итога про версию
+// принималась бы за находку и отбрасывалась.
+const CANDIDATE = /[\w.@+-]+(?:\/[\w.@+-]+)*\.[A-Za-z][A-Za-z0-9]{0,9}/g;
+
+function inScope(candidate, files) {
+  const c = normPath(candidate);
+  if (files.has(c)) return true;
+  // Совпадение по хвосту в обе стороны: инструмент печатает то абсолютный путь, то голое имя
+  // файла. Здесь лучше ошибиться в сторону «показать»: спрятанная находка — это тишина,
+  // а лишняя показанная — просто шум, который человек отметает глазами.
+  for (const f of files) {
+    if (c.endsWith(`/${f}`) || f.endsWith(`/${c}`)) return true;
+  }
+  return false;
+}
+
+// Возвращает: что осталось показать, сколько среди этого НАХОДОК и можно ли этот гейт сузить.
+//
+// `scopable: false` — важнее всего остального. Гейт, который печатает вердикт без путей
+// (проверка сообщения коммита, проверка конфига конвейера), сузить дифом нельзя. Признать его
+// успешным на этом основании значило бы получить зелёное молчание там, где проверка провалилась,
+// — ровно та тишина, против которой построен весь стандарт. Вызывающий обязан оставить такой
+// гейт красным и сказать, почему он не сужен.
+function scopeOutput(lines, files) {
+  const kept = [];
+  let findings = 0;
+  let scopable = false;
+
+  for (const raw of lines) {
+    const plain = String(raw).replace(ANSI, "");
+    const candidates = plain.match(CANDIDATE) || [];
+    if (!candidates.length) {
+      // Строка без пути — это шапка, итог или пояснение. Показываем: без неё находка теряет
+      // контекст. Находкой не считаем: иначе гейт никогда не сузился бы до нуля.
+      kept.push(raw);
+      continue;
+    }
+    scopable = true;
+    if (candidates.some((c) => inScope(c, files))) {
+      kept.push(raw);
+      findings++;
+    }
+  }
+  return { kept, findings, scopable };
+}
+
+// Файлы, изменённые относительно ссылки. Новые файлы, ещё не добавленные в индекс, тоже входят:
+// их код так же нов, как и остальной диф, а из `git diff` они не видны.
+function changedFiles(ref, cwd) {
+  const git = (args) => {
+    const r = spawnSync("git", args, { cwd, encoding: "utf8" });
+    return r.status === 0 ? String(r.stdout || "") : null;
+  };
+  // Точка расхождения, а не сама ссылка: сравнение с веткой, ушедшей вперёд, показало бы
+  // чужие изменения как свои. Если базы нет (ссылка — коммит в той же линии), берём её саму.
+  const base = (git(["merge-base", ref, "HEAD"]) || "").trim() || ref;
+  const diff = git(["diff", "--name-only", base]);
+  if (diff === null) return null;
+  const untracked = git(["ls-files", "--others", "--exclude-standard"]) || "";
+  return new Set(
+    `${diff}\n${untracked}`.split("\n").map((l) => normPath(l.trim())).filter(Boolean)
+  );
+}
+
+export { scopeOutput, changedFiles };

package/tool/program.mjs

@@ -82,6 +82,7 @@ if (IS_MAIN) {
         [`${SELF} start`, h.start],
         [`${SELF} doctor`, h.doctor],
         [`${SELF} doctor --run`, h.doctorRun],
+        [`${SELF} doctor --run --since main`, h.doctorSince],
         [`${SELF} add ${h.name}`, h.add],
         [`${SELF} find "…"`, h.find],
         [`${SELF} why "…"`, h.why],

package/tool/selfcheck/gates.sh

@@ -22,6 +22,14 @@ field() { sed -n "s/^$2:[[:space:]]*\(.*\)$/\1/p" "$1" | head -1; }
 printf '\n\033[1mtool/selfcheck/gates.sh\033[0m\n\n'
 [ -d "$CAT" ] || { echo "  каталога гейтов нет"; exit 1; }
 
+# Зрелость каждой записи одной таблицей. Правило живёт в entryLifecycle (tool/lib/manifest.mjs);
+# повторять его здесь на sh нельзя — второй источник истины расходится с первым молча.
+# Язык принудительно русский: это внутренняя проверка комплекта, и её вывод целиком русский.
+# Без этого на машине с английской локалью половина строки печаталась по-русски, половина —
+# по-английски, в одном предложении.
+LIFE="$(AQK_LANG=ru node "$ROOT/tool/selfcheck/lifecycle.mjs" 2>/dev/null)"
+life_field() { printf '%s\n' "$LIFE" | awk -F'|' -v s="$1" -v n="$2" '$1==s{print $n}'; }
+
 for GATE in "$CAT"/*/; do
   SLUG="$(basename "$GATE")"
   YML="$GATE/gate.yml"
@@ -71,9 +79,18 @@ for GATE in "$CAT"/*/; do
   printf '%s\n' "$README_TEXT" | grep -qE 'чего НЕ ловит|Чего НЕ ловит|чего не ловит|Чего не ловит' \
     || bad "$SLUG: в README нет раздела «чего НЕ ловит» — граница записи обязана быть названа"
 
-  case "$PROOF" in
-    *incidents/*) : ;;
-    *) warn "$SLUG: доказательство не ссылается на журнал шишек — запись условная" ;;
+  # Зрелость не объявляют — её считают. Попытка написать `lifecycle: stable` руками отклоняется:
+  # поле, которое заполняет автор, означает доверие к автору, а не факт. Это ровно тот способ,
+  # которым «зелёный» у соседей перестал что-либо значить, — см. kit/gates/README.md.
+  LIFE_PROBLEM="$(life_field "$SLUG" 4)"
+  # continue, а не просто отметка: запись с неверным объявлением уже отклонена, и гонять по ней
+  # образцы значит посчитать её и в отклонённых, и в принятых — итог начинает врать.
+  [ -n "$LIFE_PROBLEM" ] && { bad "$SLUG: $LIFE_PROBLEM"; continue; }
+
+  STATE="$(life_field "$SLUG" 2)"
+  case "$STATE" in
+    experimental) warn "$SLUG: доказательство не ссылается на журнал шишек — запись условная" ;;
+    deprecated)   warn "$SLUG: выведена из употребления, заменяет её «$(life_field "$SLUG" 3)»" ;;
   esac
 
   # --- образцы ---------------------------------------------------------------

package/tool/selfcheck/lifecycle.mjs

@@ -0,0 +1,29 @@
+// tool/selfcheck/lifecycle.mjs — зрелость записей каталога, одной таблицей.
+//
+// ЗАЧЕМ ОТДЕЛЬНЫМ ФАЙЛОМ, А НЕ КУСКОМ gates.sh. Правило зрелости живёт в `entryLifecycle`
+// (tool/lib/manifest.mjs) и оттуда же читается программой. Повторить его на sh значило бы
+// завести второй источник истины: через месяц приёмка и отчёт расходятся, и про одну и ту же
+// запись машина говорит разное. Здесь — только печать; решение принимает та же функция.
+//
+//   node tool/selfcheck/lifecycle.mjs        → slug|состояние|замена|проблема
+//
+// Код возврата — число записей с проблемой объявления.
+
+import { readCatalog } from "../lib/repo.mjs";
+import { entryLifecycle } from "../lib/manifest.mjs";
+import { L } from "../i18n/index.mjs";
+
+const catalog = await readCatalog();
+const slugs = new Set(catalog.map((r) => r.slug));
+let bad = 0;
+
+for (const rec of catalog) {
+  const { state, supersededBy, problem } = entryLifecycle(rec);
+  // Замена, которой нет в каталоге, — это ответ «а что теперь», ведущий в никуда. Проверяется
+  // здесь, а не в чистой функции: та не знает про остальные записи и не должна знать.
+  const why = problem || (supersededBy && !slugs.has(supersededBy) ? L.lifecycle.unknownReplacement(supersededBy) : "");
+  if (why) bad++;
+  console.log(`${rec.slug}|${state}|${supersededBy || ""}|${why}`);
+}
+
+process.exit(bad);

package/tool/selfcheck/smoke.sh

@@ -904,6 +904,59 @@ else
 fi
 rm -rf "$NRDIR" "$NRBIN"
 
+# --- 49. выведенную запись не ставят, а называют преемника --------------------
+# ЗАЧЕМ. Зрелость записи считается по доказательству, и объявить её нельзя — кроме одного
+# состояния: `deprecated`. Оно объявляется, и весь его смысл в отказе: запись, которую всё ещё
+# можно поставить одной командой, не выведена, а просто помечена. Проверяем сам отказ и то, что
+# папка гейта в проекте НЕ появилась: половина установки хуже, чем её отсутствие.
+#
+# Каталог мутируем в КОПИИ пакета, а не в этом репозитории: проверка, которая правит собственные
+# исходники, однажды упадёт посередине и оставит дерево грязным.
+DEPKG="$(mktemp -d)"; DEPRJ="$(mktemp -d)"
+cp -r "$ROOT/tool" "$ROOT/kit" "$ROOT/package.json" "$DEPKG/" 2>/dev/null
+printf 'lifecycle: deprecated\nsuperseded_by: no-print-in-prod\n' >> "$DEPKG/kit/gates/todo-without-task/gate.yml"
+( cd "$DEPRJ" && git init -q . && printf 'x = 1\n' > a.py && node "$DEPKG/tool/program.mjs" init >/dev/null 2>&1 )
+DE_OUT=$( cd "$DEPRJ" && node "$DEPKG/tool/program.mjs" add todo-without-task 2>&1 ); DE_CODE=$?
+if [ "$DE_CODE" -ne 0 ] &&
+   printf '%s' "$DE_OUT" | grep -q 'no-print-in-prod' &&
+   [ ! -d "$DEPRJ/gates/todo-without-task" ]; then
+  ok "add отказывает в выведенной записи и называет ту, что её заменяет"
+else
+  bad "выведенная запись установилась или преемник не назван" "код $DE_CODE, папка: $([ -d "$DEPRJ/gates/todo-without-task" ] && echo есть || echo нет)"
+fi
+rm -rf "$DEPKG" "$DEPRJ"
+
+# --- 50. --since показывает только то, что внёс диф ---------------------------
+# ЗАЧЕМ. Первый прогон в живом проекте показывает долг за все годы. Стену красного не разбирают
+# — проверку выключают целиком. Проверяем три исхода разом: старый долг молчит, новый краснеет,
+# а гейт, который печатает вердикт без путей, НЕ становится зелёным от того, что его нечем сузить.
+SCDIR="$(mktemp -d)"
+(
+  cd "$SCDIR" && git init -q . && git config user.email t@t && git config user.name t
+  mkdir -p src && printf 'def old():\n    print("старый долг")\n' > src/old.py
+  node "$CLI" init >/dev/null 2>&1
+  node "$CLI" add no-print-in-prod >/dev/null 2>&1
+  git add -A && git commit -qm "база" >/dev/null 2>&1
+  printf 'def fresh():\n    print("новый долг")\n' > src/fresh.py
+)
+SC_WIDE=$( cd "$SCDIR" && node "$CLI" doctor --run 2>&1 )
+SC_NARROW=$( cd "$SCDIR" && node "$CLI" doctor --run --since HEAD 2>&1 )
+if printf '%s' "$SC_WIDE"   | grep -q 'old.py' &&
+   printf '%s' "$SC_NARROW" | grep -q 'fresh.py' &&
+   ! printf '%s' "$SC_NARROW" | grep -q 'old.py'; then
+  ok "--since прячет старый долг и показывает внесённый дифом"
+else
+  bad "--since сузил не то" "широкий: $(printf '%s' "$SC_WIDE" | grep -c 'py:'), узкий: $(printf '%s' "$SC_NARROW" | grep -c 'py:')"
+fi
+# Несуществующая ссылка обязана быть отказом, а не тихим «сравнили с ничем».
+SC_BAD=$( cd "$SCDIR" && node "$CLI" doctor --run --since net-takoy-vetki 2>&1 ); SC_BADCODE=$?
+if [ "$SC_BADCODE" -ne 0 ] && printf '%s' "$SC_BAD" | grep -qi 'net-takoy-vetki'; then
+  ok "--since с несуществующей ссылкой — отказ, а не тихое сравнение с ничем"
+else
+  bad "--since проглотил неверную ссылку" "код $SC_BADCODE"
+fi
+rm -rf "$SCDIR"
+
 # --- итог -------------------------------------------------------------------
 printf '\n'
 if [ "$FAIL" -eq 0 ]; then

package/tool/selfcheck/units.mjs

@@ -11,8 +11,9 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { parseManifest, manifestWithGate, unknownKeys } from "../lib/manifest.mjs";
+import { parseManifest, manifestWithGate, unknownKeys, entryLifecycle } from "../lib/manifest.mjs";
 import { triggerVerdict, recipeFor, stems, overlap, EXT_LANG, whichSync } from "../lib/repo.mjs";
+import { scopeOutput } from "../lib/scope.mjs";
 import { assessBaseline, ITEMS, BASELINE_TOTAL } from "../lib/baseline.mjs";
 import { CATALOGS, pickLang, L } from "../i18n/index.mjs";
 import { badgeMarkdown, BADGE_RE, placesToCheck } from "../commands/badge.mjs";
@@ -274,3 +275,86 @@ test("триггер по интерфейсу отделяет фронтенд
   // Причина сокрытия называется, а не молчит: иначе «не показано» неотличимо от «нечего показать».
   assert.equal(typeof triggerVerdict(rec, { ...base, has_ui: false }).why, "string");
 });
+
+// --- зрелость записи ---------------------------------------------------------
+// ЗАЧЕМ. У всех трёх соседей поле зрелости есть, и у всех троих его ЗАПОЛНЯЕТ АВТОР: `lifecycle`
+// у зондов Scorecard, `future`/`obsolete` у критериев значка OpenSSF. Поле, которое объявляет
+// автор, означает доверие к автору, а не факт, — ровно то, против чего построен весь стандарт.
+// Поэтому зрелость здесь ВЫЧИСЛЯЕТСЯ из доказательства, а объявить её нельзя.
+test("зрелость записи считается по доказательству, а не по объявлению", () => {
+  const proven = entryLifecycle({ proof: "incidents/README.md, 2026-08-27 «печать в проде»" });
+  assert.equal(proven.state, "stable");
+  assert.equal(proven.problem, null);
+
+  const claimed = entryLifecycle({ proof: "это общепринятая хорошая практика" });
+  assert.equal(claimed.state, "experimental");
+  assert.equal(claimed.problem, null);
+  // Причина обязательна: «запись условная» без объяснения неотличимо от придирки.
+  assert.equal(typeof claimed.why, "string");
+});
+
+test("объявить себя зрелым нельзя — это самооценка", () => {
+  for (const claim of ["stable", "experimental"]) {
+    const r = entryLifecycle({ lifecycle: claim, proof: "incidents/README.md, 2026-01-01" });
+    assert.notEqual(r.problem, null);
+    // Вердикт всё равно считается сам: объявление не влияет ни на что, кроме отказа.
+    assert.equal(r.state, "stable");
+  }
+  assert.notEqual(entryLifecycle({ lifecycle: "beta", proof: "incidents/x" }).problem, null);
+});
+
+// Единственное состояние, которое ОБЪЯВЛЯЕТСЯ: из фактов записи «её больше не ставят» не
+// выводится никак. Цена объявления — обязательная замена: запись, выведенная в никуда,
+// оставляет человека без ответа на вопрос «а что теперь».
+test("выведенная запись обязана назвать замену", () => {
+  const noReplacement = entryLifecycle({ lifecycle: "deprecated", proof: "incidents/x" });
+  assert.equal(noReplacement.state, "deprecated");
+  assert.notEqual(noReplacement.problem, null);
+
+  const ok = entryLifecycle({ lifecycle: "deprecated", superseded_by: "no-print-in-prod", proof: "incidents/x" });
+  assert.equal(ok.state, "deprecated");
+  assert.equal(ok.supersededBy, "no-print-in-prod");
+  assert.equal(ok.problem, null);
+});
+
+
+// --- сужение вывода до дифа --------------------------------------------------
+// ЗАЧЕМ. Первый прогон на живом проекте даёт тысячи находок из кода, который писали годами.
+// Человек видит стену красного и выключает инструмент целиком — это причина номер один, по
+// которой такие проверки снимают. Три независимых проекта из нашего разбора умеют показывать
+// только внесённое дифом (reviewdog, ratchets `--since`, четыре режима шума у react-doctor).
+test("сужение по дифу: находка вне диапазона отбрасывается, внутри — остаётся", () => {
+  const files = new Set(["src/new.py"]);
+  const r = scopeOutput(["src/new.py:3: печать", "src/old.py:9: печать"], files);
+  assert.deepEqual(r.kept, ["src/new.py:3: печать"]);
+  assert.equal(r.findings, 1);
+});
+
+test("сужение по дифу: «./путь» и «путь» — один и тот же файл", () => {
+  const r = scopeOutput(["./src/new.py:3: печать", "src\\new.py:4: печать"], new Set(["src/new.py"]));
+  assert.equal(r.findings, 2);
+});
+
+// Тот же урок, что стоил починки в _native.sh: родные инструменты печатают путь ВНУТРИ
+// escape-последовательности, и сравнение по границе пути его не видит. Тогда «вывод
+// сократился с 5597 до 5505 строк» выглядело как работающая правка.
+test("сужение по дифу: цвет снимается до сравнения путей", () => {
+  const esc = String.fromCharCode(27);
+  const line = esc + "[32m" + "src/new.py" + esc + "[0m" + ":3: печать";
+  assert.equal(scopeOutput([line], new Set(["src/new.py"])).findings, 1);
+});
+
+test("сужение по дифу: строка без пути остаётся, но находкой не считается", () => {
+  const r = scopeOutput(["Итого: 4 нарушения", "src/old.py:1: печать"], new Set(["src/new.py"]));
+  assert.equal(r.findings, 0);
+  assert.equal(r.kept.includes("Итого: 4 нарушения"), true);
+});
+
+// САМОЕ ВАЖНОЕ ЗДЕСЬ. Гейт, который печатает вердикт без путей (проверка коммита, проверка
+// конфига конвейера), сузить дифом нельзя. Молча признать его успешным — это ровно та тишина,
+// против которой построен весь стандарт, только теперь внутри нашего же флага.
+test("сужение по дифу: гейт без путей в выводе не сужается и остаётся красным", () => {
+  const r = scopeOutput(["коммит не несёт раздела «Сделано:»"], new Set(["src/new.py"]));
+  assert.equal(r.scopable, false);
+  assert.equal(scopeOutput(["src/old.py:1: печать"], new Set(["src/new.py"])).scopable, true);
+});