@dzhechkov/harness-core 0.8.11 → 0.8.21

package/src/claim-check.ts

@@ -207,6 +207,22 @@ const REPRODUCER_HINTS = [
   'test output', 'coverage report', 'measured on',
 ];
 
+/**
+ * ЯКОРЬ СТРАНИЦЫ ПЕРВОИСТОЧНИКА — ЭТО ПРОВЕНАНС, а не украшение.
+ *
+ * Числу, взятому из книги, страница даёт то же, что репродьюсер даёт измерению: адрес, по которому
+ * его можно проверить. Требовать рядом `MEASURED` бессмысленно — мы ничего не мерили, мы
+ * процитировали; а `CLAIMED` было бы слабее правды, потому что источник НАЗВАН точнее, чем словом.
+ *
+ * ИЗМЕРЕНО 2026-09-04 на книжных пакетах: 333 находки, из них 86 несут якорь на самой строке и ещё
+ * 58 — в абзаце, то есть 144 из 333 (43%) — ложные. Их цена не в них самих: автор, видящий звон на
+ * каждую цитату, перестаёт реагировать на сигнализацию, и она пропустит настоящую находку.
+ *
+ * ГРАНИЦА ОСЛАБЛЕНИЯ, названная явно: якорь снимает требование ТЕГА и ничего больше. Утверждение
+ * «идеальная точность / 100%» он НЕ лицензирует — та ветка стоит выше и до якоря не доходит.
+ */
+const PAGE_ANCHOR_RE = /\[\s*(?:p|pp|с|стр)\.?\s?\d+/i;
+
 const PERCENT_RE = /\b(\d{1,3}(?:\.\d+)?)\s?%/g;
 // "perfect" / "100%" framing is the specific retracted claim — always high severity.
 // NOTE: no trailing \b after "%": "%"→" " is non-word→non-word, so a trailing \b
@@ -286,8 +302,15 @@ export function claimCheck(text: string): ClaimCheckResult {
     // number and is not a taggable claim (ADR-263 F11).
     if (!hasPercent && !HAS_NUMBER_RE.test(lower.replace(LABEL_TOKEN_RE, ' '))) return;
 
-    // A metric/percent with no honesty tag at all.
-    if (!tagged) {
+    // A metric/percent with no honesty tag at all — unless the paragraph carries a SOURCE PAGE
+    // anchor, which is provenance of a different and stricter kind (see PAGE_ANCHOR_RE).
+    // ЯКОРЬ НЕ ЛИЦЕНЗИРУЕТ РАМКУ «ИДЕАЛЬНО / 100%» — и проверяется это по ФОРМЕ строки, а не по
+    // ветке `perfect` выше: та требует РАСПОЗНАННОГО метрического слова, а словарь метрик
+    // англоязычный. Русское «100% точности [p.77]» до этой оговорки уходило в тишину: ветка
+    // `perfect` его не видела, а якорь снимал требование тега. Поймано СВОИМ ЖЕ тестом.
+    const perfectShape = PERFECT_WORD_RE.test(line) || PERFECT_PCT_RE.test(line);
+    const pageAnchored = PAGE_ANCHOR_RE.test(para) && !perfectShape;
+    if (!tagged && !pageAnchored) {
       findings.push({
         severity: 'medium',
         line: i + 1,

package/src/claude-hooks-assets.ts

@@ -0,0 +1,227 @@
+/**
+ * The Claude-side destructive-command guard, as an INSTALLABLE asset
+ * (feature `destructive-command-guard`, task T8, cross-family review round 3, finding P1-1).
+ *
+ * ## Why this file exists
+ *
+ * The guard shipped as one file committed at this repository's root, registered in this
+ * repository's `.claude/settings.json`. MEASURED 2026-09-05, running the documented command in a
+ * clean project — `dz setup --target claude-code --project <tmp>`:
+ *   the written `.claude/settings.json` carries SessionStart / SessionEnd / PreCompact and no
+ *   `PreToolUse` key at all, and `.claude/hooks/` does not exist.
+ * So the advertised Claude-side guard protected exactly one checkout: ours. A guard that only ever
+ * guards its author is a demo.
+ *
+ * Setup therefore has to install BOTH halves into the consumer project — the body and the registry
+ * entry — and the body must come from the INSTALLED package, never from a path inside our
+ * repository, which a consumer does not have.
+ *
+ * ## Why the body carries an absolute path
+ *
+ * The emitted hook runs from `<consumer>/.claude/hooks/`, where `require('@dzhechkov/harness-core')`
+ * cannot resolve: Node resolves a bare specifier upward from the FILE, and the package is not above
+ * that file in a global install. The body therefore resolves by PATH, and the LAST candidate is the
+ * absolute location of the installation that emitted it (see `harness-core-location.ts` for the
+ * measurement that forced this). Project-local candidates come FIRST, so a consumer that installed
+ * harness-core itself keeps using its own copy and is never pinned to ours.
+ *
+ * The generated text is behaviourally identical to this repository's own
+ * `.claude/hooks/destructive-guard.cjs`, and a test drives BOTH bodies through the same matrix
+ * rather than trusting that they stayed alike.
+ *
+ * @packageDocumentation
+ */
+
+import { harnessCoreDistDir } from './harness-core-location.js';
+
+/** Bump when the emitted BODY changes. Unlike Codex, Claude has no trust gate — this is provenance. */
+export const DZ_CLAUDE_HOOK_VERSION = 1;
+
+/**
+ * The OWNERSHIP marker. A file carrying this line is one dz wrote and may replace; a file without it
+ * belongs to the consumer and is never overwritten without `--force`.
+ *
+ * MEASURED 2026-09-05, before this existed: a hand-authored
+ * `.claude/hooks/destructive-guard.cjs` was replaced by a routine `dz setup` run, no `--force`
+ * involved — the one path in setup that was not additive. Ownership is asserted by a MARKER rather
+ * than by a hash of the bytes we wrote, because an UPGRADE must still be able to replace an older
+ * dz body; the cost of that choice is stated in the emitted file itself, on the marker line.
+ */
+export const CLAUDE_DESTRUCTIVE_HOOK_MARKER = 'dz-managed-hook: destructive-guard';
+
+/** Is this file body one dz owns? Absence of the marker is the consumer's claim to the file. */
+export function isDzManagedHookBody(body: string): boolean {
+  return body.includes(CLAUDE_DESTRUCTIVE_HOOK_MARKER);
+}
+
+/** Where the body is installed inside a consumer project, and what the registry entry points at. */
+export const CLAUDE_DESTRUCTIVE_HOOK_RELPATH = '.claude/hooks/destructive-guard.cjs';
+
+/**
+ * The command Claude Code runs — the EXACT documented placeholder, never a shell-only variant.
+ *
+ * Relative to the project rather than absolute: the settings file is committed by consumers and
+ * shared across machines, and an absolute path in it breaks for every collaborator. The BODY may
+ * carry an absolute fallback because it is generated per machine; the SETTINGS entry may not.
+ *
+ * WHY THE EXACT TOKEN [DOC, code.claude.com/docs/en/hooks, read 2026-09-06]. `${CLAUDE_PROJECT_DIR}`
+ * is a PLACEHOLDER Claude Code substitutes itself — "Use these placeholders to reference hook
+ * scripts relative to the project or plugin root, regardless of the working directory when the hook
+ * runs: ${CLAUDE_PROJECT_DIR}: the project root where the session started" — and the documentation
+ * describes NO default syntax. The previous `${CLAUDE_PROJECT_DIR:-.}` is therefore not the
+ * placeholder at all; it worked only where a POSIX shell happened to expand the variable, and on a
+ * host where Claude Code's own substitution is what fills the token in, it stays literal and the
+ * hook cannot be found. NOT REPRODUCED LIVE: there is no Windows host here, so the Windows half of
+ * this is documentation plus the reviewer's report, not a measurement of mine.
+ *
+ * MEASURED here (POSIX `sh`, 2026-09-06), which is the part that IS checkable: with the variable
+ * set the two forms are identical (`/tmp/x/p`); with it unset the exact token yields `/p` while the
+ * old form yielded `./p`. So on the only path this change can degrade — a hand-run command with no
+ * variable and no substitution — the failure is a loud "cannot find module", never a silent pass.
+ * The fallback that matters (finding the DECIDER) lives inside the body, where it can actually run.
+ */
+export const CLAUDE_DESTRUCTIVE_HOOK_COMMAND =
+  'node "${CLAUDE_PROJECT_DIR}/' + CLAUDE_DESTRUCTIVE_HOOK_RELPATH + '"';
+
+/** The PreToolUse matcher. Bash only — the decider skips every other tool without reading it. */
+export const CLAUDE_DESTRUCTIVE_HOOK_MATCHER = '^Bash$';
+
+export interface ClaudeHookAssetOptions {
+  /**
+   * Absolute directory holding the BUILT harness-core modules, baked in as the last resort.
+   * Defaults to the installation generating the file. `null` omits it — used for a body that is
+   * committed to a repository, where a machine-specific path would be wrong for everyone else.
+   */
+  readonly installedDistDir?: string | null | undefined;
+}
+
+/**
+ * The emitted `.claude/hooks/destructive-guard.cjs`.
+ *
+ * Thin by contract: read stdin, hand the payload to `decideDestructiveHook`, print, exit. Runtime
+ * failures of ours exit 0 with one loud line, but a deterministically missing decision module exits
+ * 2: setup cannot leave an armed-looking hook that allows every command until somebody builds it.
+ */
+export function generateClaudeDestructiveHook(opts: ClaudeHookAssetOptions = {}): string {
+  const installed = opts.installedDistDir === undefined ? harnessCoreDistDir() : opts.installedDistDir;
+  const bakedLine =
+    installed === null
+      ? '  // No installed path was baked in (a body committed to a repository): project-local only.\n'
+      : `  candidates.push(${JSON.stringify(installed)} + '/destructive-guard-hook.js'); // the installation that emitted this file\n`;
+
+  return `#!/usr/bin/env node
+// GENERATED by @dzhechkov/harness-core — dz-claude-hook-version: ${DZ_CLAUDE_HOOK_VERSION}
+// ${CLAUDE_DESTRUCTIVE_HOOK_MARKER}
+// Do not edit: this marker line is what tells dz the file is ITS OWN, so dz rewrites it on the next
+// 'dz setup --target claude-code'. Delete the marker line to claim the file: dz then leaves it
+// alone and only '--force' replaces it, after a timestamped backup.
+//
+// PreToolUse guard on Bash: a deletion by a LITERAL path into a protected store never runs.
+// All of the policy — the three outcomes, the refusal text, the limits the guard must name — lives
+// in @dzhechkov/harness-core (destructive-guard.js classifies, destructive-guard-hook.js decides).
+// The same module decides for the Codex host, so both runtimes refuse the same commands in the
+// same words.
+'use strict';
+
+const path = require('node:path');
+const { writeSync } = require('node:fs');
+const { pathToFileURL } = require('node:url');
+
+/**
+ * Load the decision module by PATH, project-local first, then the installation that emitted this
+ * file. 'import()' and never 'require()': harness-core is "type": "module", and require() of an ES
+ * module throws ERR_REQUIRE_ESM below Node 20.19 / 22.12 — which used to be caught and turned into
+ * a silent allow.
+ */
+async function loadDecider() {
+  // CLAUDE_PROJECT_DIR when the host set it, else this file's own location. The env var is the
+  // host's own statement of where the project root is; __dirname is what still works when nobody
+  // said anything, including when this hook is run by hand.
+  const projectRoot = process.env.CLAUDE_PROJECT_DIR || path.resolve(__dirname, '..', '..');
+  // DZ_GUARD_TRUSTED_ONLY is set by 'dz setup' while it certifies this file. The probe SPAWNS the
+  // hook, so with project-local candidates first it would import — and execute the top level of —
+  // whatever a cloned repository committed at packages/@dzhechkov/harness-core/dist/, during setup
+  // and outside the host's hook-trust flow. The receipt must certify the TRUSTED installation, so
+  // for the probe the project's own copies are switched off. At RUNTIME they stay first: a project
+  // that ships its own harness-core is exactly who should decide there.
+  const trustedOnly = process.env.DZ_GUARD_TRUSTED_ONLY === '1';
+  const candidates = trustedOnly ? [] : [
+    path.join(projectRoot, 'node_modules', '@dzhechkov', 'harness-core', 'dist', 'destructive-guard-hook.js'),
+    path.join(projectRoot, 'packages', '@dzhechkov', 'harness-core', 'dist', 'destructive-guard-hook.js'),
+  ];
+${bakedLine}  const failures = [];
+  for (const candidate of candidates) {
+    try {
+      const mod = await import(pathToFileURL(candidate).href);
+      const decide = mod.decideDestructiveHook || (mod.default && mod.default.decideDestructiveHook);
+      if (typeof decide === 'function') return { decide: decide, reason: null };
+      failures.push(candidate + ': загружен, но decideDestructiveHook не экспортирован');
+    } catch (err) {
+      const code = (err && err.code) || 'ERR_UNKNOWN';
+      failures.push(candidate + ': ' + code + ' ' + String((err && err.message) || err));
+    }
+  }
+  return { decide: null, reason: failures.join(' | ').replace(/\\s*\\n\\s*/g, ' ') };
+}
+
+let raw = '';
+process.stdin.on('data', (c) => { raw += c; });
+process.stdin.on('end', () => {
+  let payload = null;
+  try {
+    payload = JSON.parse(raw);
+  } catch (_) {
+    payload = null; // handed over as-is: the decider owns the "unreadable" wording too.
+  }
+  loadDecider().then(
+    (loaded) => onDecider(loaded, payload),
+    (err) => failOpen('страж опасных команд не смог загрузиться: ' + String((err && err.message) || err)),
+  );
+});
+
+/** One line, exit 0. Every failure of OURS ends here — loudly, and never as a refusal. */
+function failOpen(what) {
+  process.stderr.write(
+    'DZ-DESTRUCTIVE-WARN: ' + String(what).replace(/\\s*\\n\\s*/g, ' ') + ' — команда ПРОПУЩЕНА без проверки.\\n',
+  );
+  process.exit(0);
+}
+
+/** One line, exit 2. No decider means the guard installation is incomplete, so nothing may run. */
+function failUnarmed(reason) {
+  const line =
+    'DZ-DESTRUCTIVE: страж опасных команд не собран и не может проверить запрос — команда НЕ ВЫПОЛНЕНА. ' +
+      'Причина: ' + String(reason).replace(/\\s*\\n\\s*/g, ' ') +
+      ' Починка: npm install -g @dzhechkov/harness-cli@latest, затем dz setup --target claude-code.\\n';
+  // Hook stderr is a pipe under the host and under spawnSync. An immediate process.exit can drop a
+  // buffered write entirely, so write this installation verdict synchronously before exiting.
+  writeSync(2, line);
+  process.exit(2);
+}
+
+function onDecider(loaded, payload) {
+  const decide = loaded.decide;
+  if (decide === null) {
+    failUnarmed(loaded.reason);
+    return;
+  }
+
+  let out = '';
+  let code = 0;
+  try {
+    const decision = decide(payload, 'claude');
+    if (!decision || typeof decision.stderr !== 'string') {
+      throw new TypeError('решение стража нечитаемо: ' + JSON.stringify(decision));
+    }
+    out = decision.stderr;
+    code = decision.exitCode === 2 ? 2 : 0; // 2 = block the call and show the reason.
+  } catch (err) {
+    failOpen('страж опасных команд упал (' + String((err && err.message) || err) + ')');
+    return;
+  }
+
+  if (out !== '') process.stderr.write(out);
+  process.exit(code);
+}
+`;
+}

package/src/clean-room-smoke.ts

@@ -0,0 +1,195 @@
+/**
+ * Чистая комната: проверить пакет так, как его увидит НОВЫЙ пользователь.
+ *
+ * ЗАЧЕМ. Разработчик забыл включить файл в поставку — на его машине всё работает, потому что файл
+ * лежит рядом в репозитории; у покупателя коробка приходит без детали. Класс называется
+ * `files[]`/install-layout, и локальный прогон его не ловит ПО ПОСТРОЕНИЮ: он видит рабочее дерево.
+ *
+ * ЧЕСТНАЯ ГРАНИЦА, названная сразу и повторённая в вердикте: «в чистой комнате завелось» НЕ РАВНО
+ * «Claude Code пакет увидел». ИЗМЕРЕНО ранее: health-advisor 1.2.0 был зелёным в чистой комнате на
+ * пакете, чьи навыки не регистрировались вовсе. Это ДОПОЛНЕНИЕ к живой пробе регистрации, а не её
+ * замена.
+ *
+ * ЧИСТАЯ ПОЛОВИНА. Здесь нет ни Docker, ни файловой системы: `planCleanRoom` решает, ЧТО осмысленно
+ * запустить для этого манифеста, а `cleanRoomVerdict` превращает НАБЛЮДЕНИЕ в вердикт. Обе половины
+ * проверяются без контейнера; запускает их скрипт `scripts/clean-room-smoke.mjs`.
+ */
+
+/** Что и почему запускать в контейнере. `kind: 'refuse'` — смотреть нечего, и это НЕ успех. */
+export type CleanRoomPlan =
+  | {
+      readonly kind: 'bin';
+      /** Имя исполняемого файла из `bin`, которое будет вызвано с `--help`. */
+      readonly binName: string;
+      readonly argv: readonly string[];
+      readonly why: string;
+    }
+  | {
+      readonly kind: 'import';
+      /** Имя пакета, которое будет импортировано из установленной копии. */
+      readonly packageName: string;
+      readonly why: string;
+    }
+  | {
+      readonly kind: 'files-only';
+      /** Файл из поставки, чьё присутствие проверяется после установки. */
+      readonly probeFile: string;
+      readonly why: string;
+    }
+  | {
+      readonly kind: 'refuse';
+      readonly reason: string;
+    };
+
+interface ManifestLike {
+  readonly name?: unknown;
+  readonly bin?: unknown;
+  readonly main?: unknown;
+  readonly exports?: unknown;
+  readonly files?: unknown;
+  readonly private?: unknown;
+}
+
+/**
+ * Выбрать пробу по манифесту — от самой сильной к самой слабой.
+ *
+ * ПОРЯДОК НЕ ПРОИЗВОЛЕН. Запуск бинаря проверяет и установку, и разрешение зависимостей, и то,
+ * что точка входа физически приехала. Импорт проверяет первые две. Присутствие файла — только
+ * состав поставки. Слабейшая проба ВЫБИРАЕТСЯ ТОЛЬКО тогда, когда сильнее нечего запустить, и её
+ * слабость названа в тексте `why`, чтобы читатель отчёта не принял её за полную проверку.
+ */
+export function planCleanRoom(manifest: ManifestLike): CleanRoomPlan {
+  if (manifest.private === true) {
+    return { kind: 'refuse', reason: 'пакет приватный — он не публикуется, и проверять поставку не для кого' };
+  }
+  const name = typeof manifest.name === 'string' && manifest.name.trim() !== '' ? manifest.name.trim() : null;
+  if (name === null) {
+    return { kind: 'refuse', reason: 'манифест не называет пакет — установить его в чистой комнате нельзя' };
+  }
+
+  const binName = firstBinName(manifest.bin, name);
+  if (binName !== null) {
+    return {
+      kind: 'bin', binName, argv: ['--help'],
+      why: 'запуск исполняемого файла проверяет установку, разрешение зависимостей И то, что точка входа приехала в поставке',
+    };
+  }
+
+  // ИМПОРТ ОСМЫСЛЕН, ТОЛЬКО ЕСЛИ ТОЧКА ВХОДА — ЗАГРУЖАЕМЫЙ МОДУЛЬ. ИЗМЕРЕНО 2026-09-04:
+  // `@dzhechkov/keysarium-core` объявляет `main: "index.md"`, и импорт падает с «Unknown file
+  // extension ".md"» — это верное наблюдение О МАНИФЕСТЕ, но негодная ПРОБА поставки: пакет
+  // документационный, и его состав проверяется присутствием файла. Обвинять поставку в том, что
+  // объявлено в манифесте, — путать два разных дефекта.
+  if (isLoadableEntry(manifest.main) || manifest.exports !== undefined) {
+    return {
+      kind: 'import', packageName: name,
+      why: 'импорт проверяет установку и разрешение зависимостей; ЧТО пакет делает — не проверяется',
+    };
+  }
+
+  const probe = firstFile(manifest.files);
+  if (probe !== null) {
+    return {
+      kind: 'files-only', probeFile: probe,
+      why: 'у пакета нет ни исполняемого файла, ни точки входа — проверяется ТОЛЬКО то, что объявленный файл приехал; это самая слабая из проб',
+    };
+  }
+
+  return { kind: 'refuse', reason: 'манифест не объявляет ни bin, ни точки входа, ни files — запускать в чистой комнате нечего' };
+}
+
+/** Загружаемая ли это точка входа: расширение, которое Node умеет исполнять как модуль. */
+function isLoadableEntry(main: unknown): boolean {
+  return typeof main === 'string' && /\.(?:js|mjs|cjs|node)$/i.test(main.trim());
+}
+
+/** Первое имя из `bin`. Строка — это имя самого пакета (без области), объект — первый ключ. */
+function firstBinName(bin: unknown, packageName: string): string | null {
+  if (typeof bin === 'string' && bin.trim() !== '') {
+    const base = packageName.startsWith('@') ? packageName.split('/')[1] ?? packageName : packageName;
+    return base;
+  }
+  if (typeof bin === 'object' && bin !== null && !Array.isArray(bin)) {
+    for (const key of Object.keys(bin)) {
+      if (key.trim() !== '') return key;
+    }
+  }
+  return null;
+}
+
+/** Первый ОБЫЧНЫЙ путь из `files` — образцы (`*`) проверять присутствием нельзя. */
+function firstFile(files: unknown): string | null {
+  if (!Array.isArray(files)) return null;
+  for (const f of files) {
+    if (typeof f === 'string' && f.trim() !== '' && !f.includes('*')) return f.replace(/\/+$/, '');
+  }
+  return null;
+}
+
+/** Что наблюдалось в контейнере. `exitCode: null` — процесс не завершился сам (убит, срок). */
+export interface CleanRoomObservation {
+  readonly plan: CleanRoomPlan;
+  readonly installOk: boolean;
+  readonly installOutput: string;
+  readonly exitCode: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export type CleanRoomVerdict =
+  | { readonly ok: true; readonly detail: string; readonly limit: string }
+  | { readonly ok: false; readonly detail: string };
+
+/** Оговорка, которую вердикт несёт ВСЕГДА: зелень чистой комнаты ≠ регистрация у клиента. */
+export const CLEAN_ROOM_LIMIT =
+  'чистая комната доказывает, что поставка УСТАНАВЛИВАЕТСЯ и запускается; она НЕ доказывает, '
+  + 'что Claude Code увидел навыки пакета — для этого живая проба регистрации (dz skills-verify)';
+
+/**
+ * Превратить наблюдение в вердикт.
+ *
+ * УСПЕХ НЕ ВЫВОДИТСЯ ИЗ ТИШИНЫ: отсутствие вывода при нулевом коде — не доказательство запуска, и
+ * для пробы бинаря требуется НЕПУСТОЙ вывод. Установка, не завершившаяся успехом, делает любой
+ * последующий результат бессмысленным, и это говорится первой строкой.
+ */
+export function cleanRoomVerdict(o: CleanRoomObservation): CleanRoomVerdict {
+  if (o.plan.kind === 'refuse') {
+    return { ok: false, detail: `проба не выбрана: ${o.plan.reason}` };
+  }
+  if (!o.installOk) {
+    // Провалившаяся установка делает любой последующий результат бессмысленным — и это говорится
+    // ПЕРВОЙ строкой, чтобы читатель не искал причину в проверке.
+    return { ok: false, detail: `установка из тарбола НЕ прошла — всё остальное о ней ничего не говорит: ${firstLine(o.installOutput)}` };
+  }
+  if (o.exitCode === null) {
+    return { ok: false, detail: 'проба не завершилась сама (убита или истёк срок) — исход НЕ УСТАНОВЛЕН, и это не успех' };
+  }
+  if (o.exitCode !== 0) {
+    return { ok: false, detail: `проба вышла с кодом ${o.exitCode}: ${firstLine(o.stderr) || firstLine(o.stdout) || '(вывода нет)'}` };
+  }
+  if (o.plan.kind === 'bin' && o.stdout.trim() === '' && o.stderr.trim() === '') {
+    // Ноль и тишина — это не «сработало». Ровно так выглядит бинарь, чья точка входа не приехала,
+    // если оболочка проглотила ошибку: успех, выведенный из тишины, и есть тот дефект, который
+    // чистая комната обязана ловить.
+    return { ok: false, detail: 'исполняемый файл вышел с нулём и НИЧЕГО не написал — тишина не доказывает запуск' };
+  }
+  const what = o.plan.kind === 'bin' ? `\`${o.plan.binName} ${o.plan.argv.join(' ')}\``
+    : o.plan.kind === 'import' ? `импорт ${o.plan.packageName}`
+      : `присутствие ${o.plan.probeFile}`;
+  return { ok: true, detail: `установка прошла, ${what} — успешно`, limit: CLEAN_ROOM_LIMIT };
+}
+
+/**
+ * Первая строка, которая ОБЪЯСНЯЕТ отказ, а не первая непустая.
+ *
+ * ИЗМЕРЕНО 2026-09-04 на живом прогоне: у сломанной поставки первой непустой строкой оказалась
+ * `node:fs:560` — кадр стека. Такой текст в вердикте отправляет читателя в файл среды выполнения
+ * вместо причины (`ENOENT … templates/…`). Поэтому сначала ищется строка, ПОХОЖАЯ на сообщение об
+ * ошибке, и только если такой нет — берётся первая непустая.
+ */
+function firstLine(text: string): string {
+  const lines = String(text ?? '').split('\n').map((l) => l.trim()).filter((l) => l !== '');
+  const explains = lines.find((l) => /\b(?:Error|ENOENT|EACCES|ERR_[A-Z_]+|Cannot find|not found|npm ERR!)\b/i.test(l));
+  const chosen = explains ?? lines[0];
+  return chosen === undefined ? '' : chosen.slice(0, 200);
+}

package/src/cmd-usage.ts

@@ -158,14 +158,38 @@ interface RuleUsage {
 export function resolveCmdUsageRoot(startDir: string): string {
   try {
     let dir = resolve(startDir);
+    let nearestStore: string | null = null;
     for (let level = 0; level < 64; level += 1) {
-      try {
-        if (statSync(join(dir, '.dz')).isDirectory()) return dir;
-      } catch {
-        /* not here; keep walking */
+      // Ближайший `.dz` запоминается, но НЕ возвращается сразу — см. объяснение ниже.
+      if (nearestStore === null) {
+        try {
+          if (statSync(join(dir, '.dz')).isDirectory()) nearestStore = dir;
+        } catch { /* not here; keep walking */ }
+      }
+      // ГРАНИЦА РЕПОЗИТОРИЯ ВЫИГРЫВАЕТ У БЛИЖАЙШЕГО СКЛАДА, и вот почему.
+      //
+      // ИЗМЕРЕНО 2026-09-03: прогон `dz`, чей рабочий каталог оказался внутри пакета, создал там
+      // `.dz/` — и с того момента поиск останавливался на нём. Итог: 1149 записей об использовании
+      // команд уехали в склад внутри пакета вместо корневого, где их 17 265. Журнал разошёлся
+      // надвое молча, и обнаружил это только тест, требовавший корень монорепо.
+      //
+      // Тот же класс, что чинился в p-replicator неделей раньше, но зеркально: там поиск шёл ВЫШЕ
+      // границы репозитория, здесь останавливается НИЖЕ неё. Общее правило одно — у поиска корня
+      // должна быть НАЗВАННАЯ граница, а не первое попавшееся совпадение.
+      const atBoundary = ((): boolean => {
+        for (const marker of ['.git', 'pnpm-workspace.yaml']) {
+          try { statSync(join(dir, marker)); return true; } catch { /* keep checking */ }
+        }
+        return false;
+      })();
+      if (atBoundary) {
+        try {
+          if (statSync(join(dir, '.dz')).isDirectory()) return dir;
+        } catch { /* граница без склада — отдаём ближайший найденный */ }
+        return nearestStore ?? startDir;
       }
       const parent = dirname(dir);
-      if (parent === dir) return startDir;
+      if (parent === dir) return nearestStore ?? startDir;
       dir = parent;
     }
   } catch {