@dzhechkov/p-replicator 1.13.2 → 1.13.4

package/templates/.claude/hooks/check-dangling-refs.cjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * check-dangling-refs.cjs — текст ссылается на файл, которого нет?
+ *
+ * NOT an event hook. Как `check-look-trace.cjs` и соседи, лежит здесь потому, что каталог уже несёт
+ * простые утилиты на Node; в `settings.json` он не зарегистрирован и потому вправе отказывать
+ * ненулевым кодом.
+ *
+ * ─── ЗАЧЕМ ───────────────────────────────────────────────────────────────────
+ * Один класс дефекта ловился вручную минимум четыре раза: список хуков называл 4 из 8; таблица
+ * говорила «Rules 5» при шести; справка обещала 18 видов отказа при 17 в массиве; путь вывода
+ * называл каталог, которого не бывает. Форма всегда одна — ТЕКСТ ССЫЛАЕТСЯ НА ОБЪЕКТ, КОТОРОГО НЕТ,
+ * и ни одна застава об этом не спрашивала. `verify` спросить не может по построению: он обходит
+ * зарегистрированные КОМПОНЕНТЫ и проверяет их наличие, то есть идёт от объекта к тексту, а не от
+ * текста к объекту.
+ *
+ * ─── ЧТО ОН ДЕЛАЕТ, И ЧЕГО НЕ ДЕЛАЕТ ─────────────────────────────────────────
+ * Обходит отгружаемые `*.md`, вытаскивает ссылки вида `` `.claude/<путь>` `` на файлы с известными
+ * расширениями и проверяет существование цели. Он НЕ разбирает прозу и НЕ угадывает намерение:
+ * ссылка засчитывается, только если она в обратных кавычках и оканчивается на расширение из списка.
+ * Ссылка на каталог не проверяется вовсе — каталог может создаваться в работе.
+ *
+ * ─── ПОЧЕМУ БАЗА, А НЕ ПРОСТО ОТКАЗ ──────────────────────────────────────────
+ * ИЗМЕРЕНО 2026-09-03 на свежем дереве: 58 висячих ссылок в 23 файлах, и они не появляются после
+ * `init` — проверено на пустом проекте. Отказать на всех значило бы отказать каждому проекту прямо
+ * сейчас, то есть выключить заставу в первый же день. Поэтому база ЗАКРЕПЛЕНА числом и может только
+ * УМЕНЬШАТЬСЯ: новая висячая ссылка даёт отказ, а починка старой обязана уменьшить базу, иначе
+ * тест краснеет. Это тот же приём, которым в пакете уже ретирован `Final_Summary.md`: сообщаем,
+ * пока не решили, но фиксируем состояние датой и не даём ему ухудшаться.
+ *
+ * Коды: 0 — не хуже базы · 1 — база превышена (названы новые) · 2 — не удалось установить.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** ИЗМЕРЕНО 2026-09-03 на снимке дерева; может только уменьшаться. */
+const BASELINE = 58;
+
+const REF = /`(\.claude\/[A-Za-z0-9_\-./]+\.(?:cjs|mjs|js|sh|md|json|yaml|yml))`/g;
+
+function walk(dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const p = path.join(dir, e.name);
+    return e.isDirectory() ? walk(p) : [p];
+  });
+}
+
+/** Pure half: given a root holding `.claude/`, return every dangling reference found. */
+function danglingRefs(root) {
+  const base = path.join(root, '.claude');
+  if (!fs.existsSync(base)) return null; // не установлено — код 2, а не «чисто»
+  const out = [];
+  for (const file of walk(base)) {
+    if (!file.endsWith('.md')) continue;
+    const src = fs.readFileSync(file, 'utf8');
+    let m;
+    while ((m = REF.exec(src))) {
+      const target = path.join(root, m[1]);
+      if (!fs.existsSync(target)) out.push({ from: path.relative(root, file), to: m[1] });
+    }
+  }
+  return out;
+}
+
+function main(argv) {
+  const root = argv[2] || process.cwd();
+  const found = danglingRefs(root);
+  if (found === null) {
+    console.error(`НЕ УСТАНОВЛЕНО: каталог .claude не найден в ${root} — проверка не выполнялась, и это не «чисто»`);
+    return 2;
+  }
+  const unique = [...new Set(found.map((f) => `${f.from} → ${f.to}`))];
+  if (unique.length > BASELINE) {
+    console.error(`❌ висячих ссылок ${unique.length} при базе ${BASELINE} — текст обещает файлы, которых нет:`);
+    unique.slice(0, 20).forEach((u) => console.error(`   ${u}`));
+    if (unique.length > 20) console.error(`   … и ещё ${unique.length - 20}`);
+    return 1;
+  }
+  console.log(`✅ висячих ссылок ${unique.length}, база ${BASELINE} — не хуже. Проверено файлов: ${walk(path.join(root, '.claude')).filter((f) => f.endsWith('.md')).length}`);
+  if (unique.length < BASELINE) {
+    console.log(`   База устарела в лучшую сторону: опустите BASELINE до ${unique.length}, чтобы достижение закрепилось.`);
+  }
+  return 0;
+}
+
+module.exports = { danglingRefs, BASELINE, REF };
+if (require.main === module) process.exit(main(process.argv));

package/templates/.claude/hooks/check-docs-complete.cjs

@@ -43,7 +43,14 @@ const DOCS = [
   // practice — and blocking on it would have refused every project that ran like that one.
   // The discrepancy is filed; until it is settled this reports rather than refuses.
   { file: 'Final_Summary.md', optional: true, expected: true },
+  // Both entries below were made optional with no recorded reason — the gap the dated-receipt
+  // guard (`tests/unit/optional-doc-idiom.test.js`) found. What would SETTLE it is unmeasured:
+  // whether real projects produce them. So `expected` is deliberately NOT set on either — calling
+  // them expected asserts something nobody measured, calling them dispensable retires a promise
+  // silently. The receipts record the state; they do not resolve it.
+  // MEASURED 2026-09-03: promised twice by `commands/replicate.md`, required by nothing here.
   { file: 'C4_Diagrams.md', optional: true },
+  // MEASURED 2026-09-03: promised SEVEN times by `commands/replicate.md`, required by nothing here.
   { file: 'ADR.md', optional: true },
 ];
 

package/templates/.claude/hooks/check-external-deps.cjs

@@ -139,12 +139,26 @@ function section(text) {
  * an untouched template look like a filled-in inventory, which is the same substitution as an
  * absent section, one level in.
  */
+/**
+ * A markdown separator row: every cell is dashes with optional colons (`|---|:--:|`). The row
+ * directly ABOVE it is the table header — in ANY language. MEASURED 2026-09-02 (backlog b8a7669d):
+ * recognising the header by the English word `capability` alone turned the Russian header
+ * «| Возможность | Провайдер | … |» into a data row «без вердикта», and that false finding fired
+ * first and masked the real one. Position is the markdown fact; the word was a guess.
+ */
+function isSeparatorRow(line) {
+  if (!line || !line.startsWith('|')) return false;
+  const cells = line.split('|').slice(1, -1).map((c) => c.trim());
+  return cells.length > 0 && cells.every((c) => /^:?-+:?$/.test(c));
+}
+
 function rows(body) {
   const out = [];
   let templates = 0;
   let fenced = false;
-  for (const raw of body.split('\n')) {
-    const line = raw.trim();
+  const lines = body.split('\n').map((raw) => raw.trim());
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
     if (/^(```|~~~)/.test(line)) { fenced = !fenced; continue; }
     if (fenced) continue;
     if (!line.startsWith('|')) continue;
@@ -152,7 +166,8 @@ function rows(body) {
     if (cells.length < 7) continue;                    // '' + 5 columns + ''
     const capability = cells[1];
     if (!capability || /^:?-+:?$/.test(capability)) continue;
-    if (/^capability/i.test(capability)) continue;                       // header row
+    if (isSeparatorRow(lines[i + 1])) continue;        // header row, by POSITION (any language)
+    if (/^capability/i.test(capability)) continue;     // header of a table WITHOUT a separator row (belt)
     if (/^\[.*\]$/.test(capability) || capability === '...') { templates += 1; continue; }
     out.push({
       capability,

package/templates/.claude/hooks/statusline.cjs

@@ -245,7 +245,7 @@ function parseExpectedToolkit() {
     commandsExpected: 11,
     agentsExpected: 4,    // pre-shipped only (project agents are extra)
     rulesExpected: 13,    // pre-shipped only (project rules are extra)
-    hooksExpected: 25,    // 4 event hooks + statusline + state-update + writer + 15 checks + 1 capture
+    hooksExpected: 26,    // 4 event hooks + statusline + state-update + writer + 15 checks + 1 capture
   };
 }
 

package/templates/.claude/rules/cost-of-detection-ladder.md

@@ -62,9 +62,9 @@ directly—for example, a static grep cannot establish runtime resilience.
 Every safeguard must connect the reason for the property to an observable signal, a recurring trigger,
 and a response. Record it with this shape:
 
-| Cause / property | Observable signal | Check kind | Layer | Trigger / cadence | Reaction | Owner |
-|---|---|---|---|---|---|---|
-| Why the constraint exists | What changes when it is violated | How it is observed | Where it is enforced | When it runs | What happens on failure | Who acts |
+| Cause / property | Observable signal | Check kind | Layer | Scope — what it does NOT cover | Trigger / cadence | Reaction | Owner |
+|---|---|---|---|---|---|---|---|
+| Why the constraint exists | What changes when it is violated | How it is observed | Where it is enforced | The boundary, stated so nobody has to infer it | When it runs | What happens on failure | | Who acts |
 
 **Reaction must name a concrete action.** Valid reactions include: block or return the change, repair
 the practice or implementation, escalate to the named owner, or revisit the decision explicitly.
@@ -77,7 +77,12 @@ A blank cell, “note the warning,” or “the reviewer decides” does not clo
 3. Select a check kind that can observe that signal.
 4. Place the check on the strongest layer that can express it reliably.
 5. Define its trigger or cadence, concrete Reaction, and owner.
-6. Test that the safeguard fires on a deliberately bad input before trusting the happy path.
+6. Test that the safeguard FIRES on a deliberately bad input — and, in the same breath, that it
+   stays CLEAN on a correct and COMPLETE one. Both halves or neither: a guard proven only to fire is
+   indistinguishable from one that fires at everything, and a guard proven only to pass is
+   indistinguishable from one that cannot see. The two cases are cheap together and worthless apart.
+7. State the check's SCOPE — what it does not look at. Every guard has a boundary, and a boundary
+   left unsaid is read by the next person as "covers everything".
 
 ## Anti-pattern: “the critic/reviewer will catch it”
 
@@ -94,3 +99,31 @@ may complement the check for semantics; it must not carry a deterministic invari
 The same property written only as “remember to include the file” would sit on Layer 5 and could fail
 silently. The artifact test observes the real distribution boundary and defines what happens when it
 breaks.
+
+---
+
+## A guard that cannot fail is not on Layer 1 — it is decoration
+
+A check earns its layer by what it does on BAD input, not by existing. A guard nobody ever saw refuse
+is indistinguishable from a guard that cannot refuse, and the two are told apart by one act: feed it
+the thing it exists to catch and watch it go red.
+
+**The rule.** Every guard you add ships with a case that makes it FAIL. Not a case that exercises it —
+a case that would pass if the guard were deleted, and fails because it is there.
+
+Three ways a guard silently cannot fail, all of them observed:
+
+| How it dies | What it looks like | How to tell |
+|---|---|---|
+| Its predicate matches nothing | green forever, no findings ever | inject the exact shape it names; it must go red |
+| It is never invoked | green because it never ran | grep the pipeline for its invocation and for consumption of its exit code |
+| It refuses on absence | red always, for a reason unrelated to the defect | run it on known-good input; it must go green |
+
+**The honest half of this rule.** No mechanism in this package enforces it. There is no meta-test
+walking every guard and demanding a failing case beside it. Until such a test exists, this rule lives
+on **Layer 4** — it works when someone reads it and applies it, and lapses silently when nobody does.
+Writing it here does not make it Layer 1; only the meta-test would.
+
+That admission is the point. A rule that overstates its own layer is exactly the defect it warns
+about: a Layer-4 habit wearing Layer-1 clothes, which is the worst outcome the ladder describes,
+because it buys the confidence of a deterministic check while keeping the reliability of a reminder.

package/templates/.claude/rules/docker-ports.md

@@ -123,6 +123,34 @@ bindings/Compose-метки и только там проверяет runtime-а
 **Чего она НЕ делает.** Она не привязана ни к какому событию — её надо позвать. Не выводите из
 присутствия правила или последней зелёной квитанции, что кто-то продолжает смотреть за машиной.
 
+## Тестовый compose: две вещи, которые ломают не тест, а прод
+
+Обе — обобщённые из отклонённой заявки на `compose.test.yml`; правила ниже generic, самого файла в
+пакете нет и не будет.
+
+**1. Пароли тестового стека задаются через `${VAR:?}` — без значения по умолчанию.**
+
+```yaml
+environment:
+  POSTGRES_PASSWORD: ${TEST_DB_PASSWORD:?переменная обязана быть задана}
+```
+
+Запись `${VAR:-по-умолчанию}` кажется удобной и делает ровно одну вещь: превращает забытую
+переменную в ТИХО РАБОТАЮЩИЙ стек с известным паролем. Форма `:?` останавливает запуск с
+названной причиной, то есть переводит отказ из молчаливого в громкий. Пароль по умолчанию в
+тестовом стеке — это пароль по умолчанию, который однажды переедет в прод вместе с файлом.
+
+**2. Тестовый compose обязан задавать своё `name:`.**
+
+```yaml
+name: myproject-test
+```
+
+Без него docker выводит имя проекта из ИМЕНИ КАТАЛОГА, поэтому тестовый и рабочий стек в одном
+каталоге получают одно имя. Практическое следствие: `docker compose -f compose.test.yml up`
+останавливает и пересоздаёт контейнеры рабочего стека, потому что для docker это тот же проект.
+Отказ здесь не в тесте — он в том, что тест сносит то, что тестом не является.
+
 ## Быстрая самопроверка
 
 ```bash

package/templates/.claude/rules/feature-lifecycle.md

@@ -96,6 +96,27 @@ After 3 retries with 🔴, halt and surface to user.
 
 **Quality gate:** tests pass, lint clean, build succeeds.
 
+### Comment density — match the host project, not this toolkit
+
+**Правило одной строкой: комментарий пишется только для ограничения, которое КОД НЕ МОЖЕТ ПОКАЗАТЬ
+САМ, а плотность комментариев берётся от целевого репозитория, а не от этого тулкита.**
+
+Что считается таким ограничением: измеренная причина («порог 2, потому что при 1 счётчик указывает
+на одну запись»), внешний контракт, который нельзя вывести из кода, ссылка на инцидент, объясняющая
+неочевидную защиту. Что им НЕ является: пересказ того, что делает следующая строка; заголовок
+раздела; преамбула о замысле функции, чьё имя уже это говорит.
+
+**Почему это правило здесь.** [FIELD, 2026-08-30] Коллега владельца о сгенерированном коде:
+«пишется очень много документации, в коде в основном одни комментарии, это переполняет контекст».
+ИЗМЕРЕНО 2026-09-03 на отгружаемых шаблонах этого пакета: проза составляет 70,3% их объёма
+(1 105 072 байта разметки против 466 914 байт кода), а внутри самого кода комментарии занимают
+33,6% (156 660 байт). Это стиль ЭТОГО репозитория, и в нём он оправдан: код тут читают агенты,
+которым неоткуда узнать историю. В чужом проекте он и чужая конвенция, и налог на контекст каждого
+будущего чтения.
+
+**Практическая проверка перед тем, как оставить комментарий:** удалите его мысленно и спросите,
+теряется ли при этом факт, который нельзя восстановить из кода. Нет — удаляйте по-настоящему.
+
 ### Positive file receipt (required)
 
 Each unit gets a unique `WORK_UNIT_ID` and unique absolute `TRACE_PATH`. Its worker MUST write a

package/templates/.claude/rules/replicate-pipeline.md

@@ -215,14 +215,14 @@ are project-agnostic and can be enhanced (read by Phase 3) but never recreated.
 [`incoming-webhooks`](incoming-webhooks.md), [`long-running-job`](long-running-job.md),
 [`model-call-cost`](model-call-cost.md)
 
-**Hooks (25 files in `.claude/hooks/`, cross-platform Node).** Only four are wired to an
+**Hooks (26 files in `.claude/hooks/`, cross-platform Node).** Only four are wired to an
 event in `.claude/settings.json`; the rest are utilities you invoke deliberately, and the
 difference matters — a hook of this package is NON-BLOCKING by contract and can only print.
 
 *Wired to an event (4):* `session-insights.cjs` (SessionStart) · `autocommit-roadmap.cjs`,
 `autocommit-insights.cjs`, `autocommit-plans.cjs` (Stop)
 
-*Invoked deliberately, wired to nothing (21):* `statusline.cjs` (a statusLine, not a hook) ·
+*Invoked deliberately, wired to nothing (22):* `statusline.cjs` (a statusLine, not a hook) ·
 `state-update.cjs` (argv utility) · `write-insight.cjs` (harvest carrier writer) ·
 `check-ports.cjs` (docker-ports Правило №0, exits 0/1/2) ·
 `check-docs-complete.cjs` (are the Phase-1 documents written, exits 0/1/2) ·
@@ -236,7 +236,7 @@ safe against reordering, exits 0/1/2)
 `check-job-contract.cjs` (does long-running work have a handle, three states and a resuming retry, exits 0/1/2)
 `check-model-cost.cjs` (does every external model call name a binding spend ceiling, exits 0/1/2) ·
 `check-review-contract.cjs` (does review-report.md answer every AC id and name the spec revision it judged, exits 0/1/2)
-`check-canon.cjs` (before a WRITING fan-out: is the shared canon named and pinned, exits 0/1/2)
+`check-canon.cjs` · `check-dangling-refs.cjs` (before a WRITING fan-out: is the shared canon named and pinned, exits 0/1/2)
 `check-file-ownership.cjs` (one writer per file, and a split-born file owned at creation, exits 0/1/2)
 `check-source-version.cjs` (does every edit and verdict declare the source version it was built on, exits 0/1/2)
 `check-handoff-manifest.cjs` (did every enumerated Phase-0 output get an answer from Phase 1, exits 0/1/2)

package/templates/.claude/skills/brutal-honesty-review/resources/assessment-rubrics.md

@@ -21,12 +21,22 @@
 |-------|----------|---------|
 | 🔴 **Failing** | Crashes on invalid input | Uncaught exceptions, panics |
 | 🟡 **Passing** | Returns error codes/exceptions | `try/catch`, error returns |
-| 🟢 **Excellent** | Graceful degradation + logging | Circuit breakers, retry logic |
+| 🟢 **Excellent** | Graceful degradation + logging — **но НЕ для значения, которое продукт ОТДАЁТ наружу** | Circuit breakers, retry logic |
+
+> **Оговорка к высшей оценке, и она несущая.** Мягкая деградация заслуживает 🟢 для НЕДОСТУПНОСТИ
+> (сервис не ответил — вернём кэш, попробуем позже) и заслуживает 🔴 для ЗНАЧЕНИЯ, которое уходит
+> потребителю (цена, остаток, право доступа, результат расчёта). Подставить приблизительное вместо
+> точного и записать это в журнал — значит выдать неверный ответ и назвать это устойчивостью.
+> Правильный исход для значения — ОТКАЗ С НАЗВАННОЙ ПРИЧИНОЙ, а не правдоподобная замена.
+>
+> Оговорка появилась потому, что прежняя формулировка прямо ПООЩРЯЛА механизм, который в разборе
+> реальных отказов назван причиной каждого происшествия высшей категории: подстановка запасного
+> значения там, где честный ответ — «не знаю».
 
 ### Concurrency Safety
 | Level | Criteria | Example |
 |-------|----------|---------|
-| 🔴 **Failing** | Race conditions, deadlocks | Shared mutable state, no locks |
+| 🔴 **Failing** | Race conditions, deadlocks; **а также: последовательный тест, поданный как доказательство параллельной безопасности** | Shared mutable state, no locks; «тест проходит» при одном писателе |
 | 🟡 **Passing** | Thread-safe with locks | Proper mutex usage |
 | 🟢 **Excellent** | Lock-free or proven safe | Immutable data, atomic operations |
 

package/templates/.claude/skills/cc-toolkit-generator-enhanced/references/security-patterns-library.md

@@ -49,6 +49,28 @@ ALWAYS use parameterized set_config():
   `SET LOCAL key = '${value}'`. Applies to all session-level config.
 ```
 
+**Шесть строк к S-01 и S-02, каждая ловит отдельный способ обойти изоляцию арендаторов:**
+
+```
+RULE: BYPASSRLS on the service role is NOT a safety net — it is the removal of one.
+      Under it a FORGOTTEN tenant filter returns other tenants' rows SILENTLY,
+      with no error to notice. Reserve it for migrations, never for request paths.
+RULE: SET LOCAL ROLE, never SET ROLE. Plain SET ROLE outlives the transaction and
+      leaks into whatever the pooled connection serves next.
+RULE: current_setting('app.tenant_id', true) — the second argument makes a missing
+      setting return NULL instead of raising. Without it an unset tenant is an
+      exception you will catch and swallow; with it, it is a value you can test for.
+RULE: Tests MUST NOT run as a superuser. A superuser bypasses RLS unconditionally,
+      so every policy test passes and proves nothing.
+RULE: A table carrying a policy but no CROSS-TENANT test counts as UNPROTECTED.
+      The policy is a claim; the test is the evidence.
+```
+
+**Почему они здесь, а не отдельным разделом.** Каждая — способ, которым изоляция ЕСТЬ в коде и
+НЕ РАБОТАЕТ на прогоне. Все пять отказывают молча: под `BYPASSRLS` нет ошибки, у суперпользователя
+нет ошибки, у утёкшей роли нет ошибки. Молчаливый отказ защиты — единственный вид, который доживает
+до продакшена, потому что громкий чинят в первый же день.
+
 ---
 
 ### S-03: Fail-Fast Secret Validation at Startup
@@ -159,6 +181,29 @@ NEVER: expose stack traces in production error responses
 
 ---
 
+### S-08: Image Type Comes From CONTENT, Never From `Content-Type`
+
+**Pattern:**
+```
+RULE: An uploaded image's type is decided by INSPECTING ITS BYTES, never by the
+      Content-Type header or the file extension — both are attacker-supplied.
+RULE: SVG is REJECTED WHOLESALE for user uploads. It is a script-bearing document
+      that happens to render as a picture; sanitising it is a losing arms race.
+RULE: Serve user-supplied files with `X-Content-Type-Options: nosniff`, so a browser
+      cannot re-decide the type you already decided.
+
+NEVER: trust `req.file.mimetype` as the type
+NEVER: allow `image/svg+xml` through an "allowed image types" list
+NEVER: serve uploads from the same origin as the application without nosniff
+```
+
+**Why all three, and not just the first.** Sniffing the bytes stops a `.png` that is really a
+script. It does NOT stop SVG, because an SVG genuinely IS an image by content and genuinely CAN
+carry script. And neither stops a browser that ignores your decision and sniffs for itself — that
+is what the header is for. Drop any one of the three and the other two leave a path open.
+
+---
+
 ## Integration Patterns for Generated Toolkit
 
 ### How Patterns Map to Generated Files

package/tests/dz-availability.js

@@ -0,0 +1,34 @@
+'use strict';
+
+/**
+ * Backlog 1b4857a6. Several cases here need a REAL `dz` on PATH — they delete or read the `.dz`
+ * state that only dz creates. The insight writer already reports the two ways that can go wrong
+ * with DIFFERENT words: `absent` is ENOENT on the spawn (no dz anywhere), `failed` is dz running
+ * and erroring. Conflating them is what made these cases green on a developer machine, where a
+ * global dz happens to be installed, and red on a CI runner, where nothing installs one:
+ * MEASURED 2026-09-19 (runs 35433442559, 35434913155, 35444026540) — `'absent' !== 'ok'`.
+ *
+ * So a MISSING TOOL is an audible skip and a BROKEN TOOL stays red. The skip is printed as well as
+ * registered, because a silent skip is how a test stops proving anything without anyone noticing —
+ * the same contract `announceNpmSkip` keeps in `tests/npm-cli-resolver.js`.
+ *
+ * Deliberately self-contained: `tests/` is published with this package (see `files` in
+ * package.json), so nothing here may reach outside it.
+ */
+
+/**
+ * @param {{skip:(reason:string)=>void}} t — the node:test context
+ * @param {string} teachState — the writer's `teach.state`
+ * @param {string} caseNote — what this case needs dz FOR, in one clause
+ * @returns {boolean} true when the case must stop (dz is absent and the skip is registered)
+ */
+function skipWhenDzAbsent(t, teachState, caseNote) {
+  if (teachState !== 'absent') return false;
+  const reason = `SKIPPED — this case needs a real \`dz\` on PATH (${caseNote}); the writer `
+    + 'reported teach.state=absent, which is ENOENT on the spawn — no dz was found, not dz failing.';
+  process.stdout.write(`${reason}\n`);
+  t.skip(reason);
+  return true;
+}
+
+module.exports = { skipWhenDzAbsent };

package/tests/e2e/packed-insights-writer.test.js

@@ -7,6 +7,7 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { skipWhenDzAbsent } = require('../dz-availability.js');
 
 const PKG = path.resolve(__dirname, '..', '..');
 const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm';
@@ -220,12 +221,15 @@ describe('PR-022 exact packed artifact', () => {
     } finally { fs.rmSync(consumer, { recursive: true, force: true }); }
   });
 
-  test('P17 - deleting .dz retains the packed Markdown record and local delivery', () => {
+  test('P17 - deleting .dz retains the packed Markdown record and local delivery', (t) => {
     const { consumer } = installConsumer();
     try {
       const record = insight({ title: LOCAL_PACKED });
       const written = parseReceipt(runPackedWriter(consumer, record, { path: process.env.PATH }));
       assert.equal(written.status, 'created');
+      // Backlog 1b4857a6: a MISSING dz is an audible skip, a BROKEN dz stays red. The rule and
+      // its reasoning live once, in tests/dz-availability.js.
+      if (skipWhenDzAbsent(t, written.teach.state, 'it deletes the .dz state that only dz creates')) return;
       assert.equal(written.teach.state, 'ok');
 
       const query = run('dz', ['recall', '--all', '--json', '--project', consumer], {