@dzhechkov/p-replicator 1.10.4 → 1.12.0

package/templates/.claude/hooks/session-insights.cjs

@@ -1,40 +1,173 @@
 #!/usr/bin/env node
 'use strict';
 
-/**
- * SessionStart hook — injects up to 3 most recent insights from
- * .claude/insights/index.md into Claude's initial session context (via stdout).
- *
- * Cross-platform: pure Node, no shell pipes. Silent on missing index.
- */
-
+const childProcess = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 
-// The project root, never the process cwd: a `cd` inside any tool call moves cwd for the rest of
-// the session, and these hooks are non-blocking, so a wrong anchor fails SILENTLY. CLAUDE_PROJECT_DIR
-// first — the host is authoritative about what the project is. `__dirname` second: a hook always
-// lives at <project>/.claude/hooks/<x>.cjs, so its own location settles the root with no cooperation
-// from anyone, which is what keeps this working when the variable is absent (hand-run, older host).
+const DOMAIN = 'p-replicator-insights';
+const MAX_RENDER_BYTES = 16 * 1024;
+const PROCESS_OPTIONS = Object.freeze({
+  encoding: 'utf8',
+  timeout: 1500,
+  killSignal: 'SIGTERM',
+  maxBuffer: 1024 * 1024,
+  shell: false,
+});
+const MISSING_HINT = 'инсайтов пока нет; /myinsights создаст первую запись\n';
 const ENV_ROOT = process.env.CLAUDE_PROJECT_DIR;
-// isAbsolute, not just truthy: a RELATIVE value would still be resolved against the drifting
-// cwd, which is the very bug this anchor exists to remove.
 const ROOT = (ENV_ROOT && path.isAbsolute(ENV_ROOT))
   ? ENV_ROOT
   : path.resolve(__dirname, '..', '..');
 
-const INDEX = path.resolve(ROOT, '.claude', 'insights', 'index.md');
+function parseHookEvent(raw = '') {
+  const text = String(raw || '').trim();
+  if (!text) return { kind: 'session-start' };
+  let parsed;
+  try { parsed = JSON.parse(text); } catch (_error) {
+    return { kind: 'user-prompt', prompt: '' };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { kind: 'user-prompt', prompt: '' };
+  }
+  const eventName = parsed.hook_event_name || parsed.hookEventName;
+  if (eventName === 'SessionStart') return { kind: 'session-start' };
+  for (const key of ['prompt', 'user_prompt', 'userPrompt']) {
+    if (typeof parsed[key] === 'string' && parsed[key].trim()) {
+      return { kind: 'user-prompt', prompt: parsed[key].trim() };
+    }
+  }
+  return eventName === 'UserPromptSubmit'
+    ? { kind: 'user-prompt', prompt: '' }
+    : { kind: 'session-start' };
+}
 
-try {
-  if (!fs.existsSync(INDEX)) process.exit(0);
-  const text = fs.readFileSync(INDEX, 'utf8');
-  // Each insight starts with "## " heading (per insights-capture.md convention).
+function readLocalCarrier(root) {
+  const index = path.resolve(root, '.claude', 'insights', 'index.md');
+  if (!fs.existsSync(index)) return { kind: 'missing', context: '' };
+  const text = fs.readFileSync(index, 'utf8');
   const sections = text.split(/^## /m).filter(Boolean);
-  const recent = sections.slice(-3).map((s) => '## ' + s.trim()).join('\n\n');
-  if (recent.length > 0) {
-    process.stdout.write('## Recent project insights\n\n' + recent + '\n');
+  const recent = sections.slice(-3).map((section) => '## ' + section.trim()).join('\n\n');
+  if (!recent) return { kind: 'empty', context: '' };
+  return { kind: 'populated', context: '## Recent project insights\n\n' + recent };
+}
+
+function truncateUtf8(value, maxBytes) {
+  const bytes = Buffer.from(value, 'utf8');
+  if (bytes.length <= maxBytes) return value;
+  let end = maxBytes;
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) end -= 1;
+  return bytes.subarray(0, end).toString('utf8');
+}
+
+function renderRecallContext(rows) {
+  const patterns = rows
+    .filter((row) => row && row.domain === DOMAIN && typeof row.pattern === 'string')
+    .map((row) => row.pattern.trim())
+    .filter(Boolean)
+    .slice(0, 3);
+  if (!patterns.length) return undefined;
+  const heading = `## Recalled project insights (dz; ${patterns.length} hits)\n\n`;
+  const body = truncateUtf8(patterns.join('\n\n'), MAX_RENDER_BYTES - Buffer.byteLength(heading));
+  return body ? { context: heading + body, hitCount: patterns.length } : undefined;
+}
+
+function processFailure(error) {
+  if (error && error.code === 'ENOENT') return { kind: 'absent' };
+  if (error && error.code === 'ETIMEDOUT') return { kind: 'failing', reason: 'timeout' };
+  const code = error && typeof error.code === 'string' && /^[A-Z0-9_-]{1,32}$/.test(error.code)
+    ? error.code
+    : 'unknown';
+  return { kind: 'failing', reason: `spawn ${code}` };
+}
+
+function recallFromDz(prompt, root, { runner = childProcess.spawnSync } = {}) {
+  let result;
+  try {
+    // --domain is a rank BOOST, not a filter: the caller still keeps only records whose domain
+    // matches exactly. Without it, a shared multi-domain store buries insight records below the
+    // top-12 cut and the armed state effectively never fires.
+    result = runner('dz', ['recall', prompt, '--limit', '12', '--domain', DOMAIN, '--project', root, '--json'], {
+      ...PROCESS_OPTIONS,
+      cwd: root,
+    });
+  } catch (error) {
+    return processFailure(error);
+  }
+  if (result.error) return processFailure(result.error);
+  if (result.status !== 0) {
+    const status = Number.isInteger(result.status) ? result.status : 'unknown';
+    return { kind: 'failing', reason: `exit ${status}` };
+  }
+  let rows;
+  try { rows = JSON.parse(result.stdout || ''); } catch (_error) {
+    return { kind: 'failing', reason: 'invalid JSON' };
   }
-} catch (_err) {
-  // Hook is advisory — never block the session on errors here.
-  process.exit(0);
+  if (!Array.isArray(rows)) return { kind: 'failing', reason: 'invalid result' };
+  const rendered = renderRecallContext(rows);
+  return rendered ? { kind: 'ok', ...rendered } : { kind: 'empty' };
 }
+
+function renderPromptEnvelope(additionalContext) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext,
+    },
+  }) + '\n';
+}
+
+function emitContext(context, output) {
+  if (typeof context === 'string' && context.trim()) {
+    output.write(renderPromptEnvelope(context));
+  }
+}
+
+function selectInsightOutput(localContext, recall) {
+  if (recall.kind === 'failing') {
+    return {
+      source: 'local',
+      context: `dz recall unavailable: ${recall.reason}; using local recent insights\n\n${localContext}`,
+    };
+  }
+  return { source: 'local', context: localContext };
+}
+
+function emitInsights(root = ROOT, output = process.stdout, dependencies = {}) {
+  try {
+    const event = parseHookEvent(dependencies.rawEvent || '');
+    const local = readLocalCarrier(root);
+    if (event.kind === 'session-start') {
+      if (local.kind === 'missing') output.write(MISSING_HINT);
+      return;
+    }
+    if (local.kind !== 'populated') return;
+    if (!event.prompt) {
+      emitContext(local.context, output);
+      return;
+    }
+    const recall = recallFromDz(event.prompt, root, { runner: dependencies.runner });
+    if (recall.kind === 'ok') {
+      emitContext(recall.context, output);
+      return;
+    }
+    const selected = selectInsightOutput(local.context, recall);
+    emitContext(selected.context, output);
+  } catch (_error) {}
+}
+
+function main() {
+  let rawEvent = '';
+  try { rawEvent = fs.readFileSync(0, 'utf8'); } catch (_error) {}
+  emitInsights(ROOT, process.stdout, { rawEvent });
+}
+
+module.exports = {
+  emitInsights,
+  parseHookEvent,
+  recallFromDz,
+  renderPromptEnvelope,
+  selectInsightOutput,
+};
+
+if (require.main === module) main();

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

@@ -244,8 +244,8 @@ function parseExpectedToolkit() {
     skillsExpected: 10,
     commandsExpected: 11,
     agentsExpected: 4,    // pre-shipped only (project agents are extra)
-    rulesExpected: 6,     // pre-shipped only (project rules are extra)
-    hooksExpected: 9,     // 4 v1.4.1 hooks + statusline + state-update + 3 deliberate checks
+    rulesExpected: 9,     // pre-shipped only (project rules are extra)
+    hooksExpected: 10,    // 4 event hooks + statusline + state-update + writer + 3 deliberate checks
   };
 }
 

package/templates/.claude/hooks/write-insight.cjs

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('node:crypto');
+const childProcess = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const CARRIER = path.join('.claude', 'insights', 'index.md');
+const DATE_HEADING = /^##\s+\d{4}-\d{2}-\d{2}/gm;
+const TEACH_OPTIONS = Object.freeze({
+  encoding: 'utf8',
+  timeout: 1500,
+  killSignal: 'SIGTERM',
+  maxBuffer: 1024 * 1024,
+  shell: false,
+});
+
+class InsightValidationError extends Error {}
+
+function normalizeText(value, field, { singleLine = false } = {}) {
+  if (typeof value !== 'string') {
+    throw new InsightValidationError(`${field} must be a string`);
+  }
+  const normalized = value.replace(/\r\n?/g, '\n').trim();
+  if (!normalized) throw new InsightValidationError(`${field} must not be blank`);
+  if (singleLine && normalized.includes('\n')) {
+    throw new InsightValidationError(`${field} must be one line`);
+  }
+  return normalized;
+}
+
+function normalizeArray(value, field) {
+  if (!Array.isArray(value)) {
+    throw new InsightValidationError(`${field} must be an array`);
+  }
+  return value.map((member, index) => {
+    if (typeof member !== 'string') {
+      throw new InsightValidationError(`${field}[${index}] must be a string`);
+    }
+    const normalized = member.replace(/\r\n?/g, '\n').trim();
+    if (normalized.includes('\n')) {
+      throw new InsightValidationError(`${field}[${index}] must be one line`);
+    }
+    return normalized;
+  }).filter(Boolean);
+}
+
+function normalizeDate(value) {
+  const date = normalizeText(value, 'date', { singleLine: true });
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+    throw new InsightValidationError('date must use YYYY-MM-DD');
+  }
+  const parsed = new Date(`${date}T00:00:00.000Z`);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== date) {
+    throw new InsightValidationError('date must be a real calendar date');
+  }
+  return date;
+}
+
+function normalizePayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new InsightValidationError('payload must be one JSON object');
+  }
+  return {
+    date: normalizeDate(payload.date),
+    title: normalizeText(payload.title, 'title', { singleLine: true }),
+    tags: normalizeArray(payload.tags, 'tags'),
+    problem: normalizeText(payload.problem, 'problem'),
+    solution: normalizeText(payload.solution, 'solution'),
+    references: normalizeArray(payload.references, 'references'),
+  };
+}
+
+function semanticId(record) {
+  const semantic = {
+    title: record.title,
+    tags: record.tags,
+    problem: record.problem,
+    solution: record.solution,
+    references: record.references,
+  };
+  return crypto.createHash('sha256').update(JSON.stringify(semantic)).digest('hex');
+}
+
+function stableTeachText(record) {
+  const tags = record.tags.length ? record.tags.join(', ') : 'none';
+  const references = record.references.length ? record.references.join(', ') : 'none';
+  // Date stays out because cross-date semantic duplicates must share one projection identity.
+  return [
+    'p-replicator insight',
+    `Title: ${record.title}`,
+    `Tags: ${tags}`,
+    'Problem:',
+    record.problem,
+    'Solution:',
+    record.solution,
+    `References: ${references}`,
+  ].join('\n');
+}
+
+function teachFailure(error) {
+  if (error && error.code === 'ENOENT') return { state: 'absent' };
+  if (error && error.code === 'ETIMEDOUT') return { state: 'failed', reason: 'timeout' };
+  const code = error && typeof error.code === 'string' && /^[A-Z0-9_-]{1,32}$/.test(error.code)
+    ? error.code
+    : 'unknown';
+  return { state: 'failed', reason: `spawn ${code}` };
+}
+
+function teachDuplicate(record, projectRoot, { runner = childProcess.spawnSync } = {}) {
+  let temporary;
+  try {
+    temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'p-replicator-insight-teach-'));
+    const input = path.join(temporary, 'insight.json');
+    const rows = [{
+      pattern: stableTeachText(record),
+      type: 'lesson-learned',
+      reward: 0.8,
+      domain: 'p-replicator-insights',
+    }];
+    fs.writeFileSync(input, JSON.stringify(rows) + '\n', { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    let result;
+    try {
+      result = runner('dz', ['teach', '--from-json', input, '--project', projectRoot], {
+        ...TEACH_OPTIONS,
+        cwd: projectRoot,
+      });
+    } catch (error) {
+      return teachFailure(error);
+    }
+    if (result.error) return teachFailure(result.error);
+    if (result.status !== 0) {
+      const status = Number.isInteger(result.status) ? result.status : 'unknown';
+      return { state: 'failed', reason: `exit ${status}` };
+    }
+    return { state: 'ok' };
+  } catch (_error) {
+    return { state: 'failed', reason: 'prepare import' };
+  } finally {
+    if (temporary) {
+      try { fs.rmSync(temporary, { recursive: true, force: true }); } catch (_error) {}
+    }
+  }
+}
+
+function renderEntry(record, id) {
+  const tags = record.tags.length ? record.tags.join(', ') : 'none';
+  const references = record.references.length ? record.references.join(', ') : 'none';
+  return [
+    `## ${record.date} — ${record.title}`,
+    '',
+    `<!-- insight-id: sha256:${id} -->`,
+    `**Tags:** ${tags}`,
+    '',
+    '**Problem:**',
+    record.problem,
+    '',
+    '**Solution:**',
+    record.solution,
+    '',
+    `**References:** ${references}`,
+    '',
+    '---',
+    '',
+  ].join('\n');
+}
+
+function entryCount(content) {
+  return (content.match(DATE_HEADING) || []).length;
+}
+
+function appendBoundary(content) {
+  if (!content) return '';
+  if (content.endsWith('\n\n')) return '';
+  if (content.endsWith('\n')) return '\n';
+  return '\n\n';
+}
+
+function atomicReplace(index, content) {
+  const temporary = `${index}.tmp-${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+  try {
+    fs.writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx' });
+    fs.renameSync(temporary, index);
+  } catch (error) {
+    try { fs.rmSync(temporary, { force: true }); } catch (_cleanupError) {}
+    throw error;
+  }
+}
+
+function writeInsight(projectRoot, payload, options = {}) {
+  if (typeof projectRoot !== 'string' || !path.isAbsolute(projectRoot)) {
+    throw new InsightValidationError('project root must be absolute');
+  }
+
+  // Validate the complete record before even creating the missing parent directory.
+  const record = normalizePayload(payload);
+  const id = semanticId(record);
+  const marker = `<!-- insight-id: sha256:${id} -->`;
+  const insightsDir = path.resolve(projectRoot, '.claude', 'insights');
+  const index = path.join(insightsDir, 'index.md');
+  const existed = fs.existsSync(index);
+  const current = existed ? fs.readFileSync(index, 'utf8') : '';
+
+  let receipt;
+  if (current.includes(marker)) {
+    receipt = { status: 'duplicate', path: CARRIER.split(path.sep).join('/'),
+      entryCount: entryCount(current), id: `sha256:${id}` };
+  } else {
+    const next = current + appendBoundary(current) + renderEntry(record, id);
+    fs.mkdirSync(insightsDir, { recursive: true });
+    atomicReplace(index, next);
+    receipt = { status: existed ? 'appended' : 'created', path: CARRIER.split(path.sep).join('/'),
+      entryCount: entryCount(next), id: `sha256:${id}` };
+  }
+  receipt.teach = teachDuplicate(record, projectRoot, options);
+  return receipt;
+}
+
+function projectRoot() {
+  const fromHost = process.env.CLAUDE_PROJECT_DIR;
+  return (fromHost && path.isAbsolute(fromHost))
+    ? fromHost
+    : path.resolve(__dirname, '..', '..');
+}
+
+function main() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (_error) {
+      throw new InsightValidationError('stdin must contain one valid JSON object');
+    }
+    const result = writeInsight(projectRoot(), parsed);
+    if (result.teach.state === 'failed') {
+      process.stderr.write(
+        `[write-insight] dz teach unavailable: ${result.teach.reason}; Markdown retained\n`,
+      );
+    }
+    process.stdout.write(JSON.stringify(result) + '\n');
+  } catch (error) {
+    const kind = error instanceof InsightValidationError ? 'invalid input' : 'write failed';
+    process.stderr.write(`[write-insight] ${kind}: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { writeInsight, normalizePayload, stableTeachText, teachDuplicate };
+
+if (require.main === module) main();

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

@@ -0,0 +1,96 @@
+# Cost-of-Detection Ladder
+
+Use this rule when you design a safeguard for an engineering or architectural property. The goal is
+to detect a violation early, consistently, and close the loop with a named response.
+
+Put every safeguard on the **strongest layer that can reliably express the property**. “Strongest”
+means cheapest to run, most deterministic, and hardest to skip. Move down the ladder only when the
+property cannot be observed faithfully on a stronger layer.
+
+## The ladder (strongest to weakest)
+
+### Layer 1 — Deterministic test, CI check, or static guard
+
+Use a repeatable executable check for properties such as file presence, size, format, exact paths,
+schema shape, forbidden strings, and locally testable behavior. This layer is fast, machine-readable,
+and does not depend on a model noticing the problem.
+
+### Layer 2 — Always-loaded governance
+
+Use a rule or role document that is loaded on every relevant run for structural guidance that needs
+context but must remain continuously visible. State the invariant and the evidence expected from the
+implementation; do not rely on prose alone when Layer 1 can express the same property.
+
+### Layer 3 — Pipeline gate
+
+Use a named pipeline step that records a machine-readable verdict for cross-artifact, workflow, or
+semantic properties. A semantic or adversarial check may use an independent model-backed gate here,
+but its verdict must be stored and the failure action must be explicit.
+
+### Layer 4 — Skill or reviewer judgment
+
+Use task-invoked specialist judgment for properties that genuinely require interpretation and cannot
+be made into a reliable stronger-layer gate. Its output is evidence for a decision, not a substitute
+for a deterministic check that could have run earlier.
+
+### Layer 5 — Agent memory or informal recall
+
+Use memory, convention, or “vibes” only as a prompt to create a real safeguard. This is the weakest
+layer because it is probabilistic, easy to omit, and silent when forgotten.
+
+## Choose the check kind from the signal
+
+**Check kind and enforcement layer are separate axes.** First identify the observable signal and the
+mechanism that can observe it. Then place that mechanism on the strongest reliable layer above.
+
+| Nature of the observable signal | Suitable check kind |
+|---|---|
+| Static structure or format | Static check or deterministic test |
+| Local behavior | Unit test |
+| Component interaction | Integration or contract test |
+| Behavior over time | Monitor with a defined threshold or invariant |
+| Runtime quantity | Metric and threshold alert |
+| Discrete transition | Event or audit check |
+| Failure resilience | Controlled fault injection |
+| Semantic or adversarial property | Independent model-backed review gate with a recorded verdict |
+
+Use only the rows relevant to the property. A mechanism is unsuitable if it cannot observe the signal
+directly—for example, a static grep cannot establish runtime resilience.
+
+## Close the loop with a reaction
+
+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 |
+
+**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.
+A blank cell, “note the warning,” or “the reviewer decides” does not close the loop.
+
+## Design procedure
+
+1. State the property and why it exists.
+2. Name the observable signal produced by a violation.
+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.
+
+## Anti-pattern: “the critic/reviewer will catch it”
+
+Deterministic properties must not be delegated to probabilistic review. If a short test can check a
+path, count, format, registry entry, or forbidden value, put that check on Layer 1. Reviewer judgment
+may complement the check for semantics; it must not carry a deterministic invariant by itself.
+
+## Worked example
+
+| Cause / property | Observable signal | Check kind | Layer | Trigger / cadence | Reaction | Owner |
+|---|---|---|---|---|---|---|
+| Required configuration must ship with the package | The packed file list lacks the required path | Deterministic artifact-membership test | 1 | Every package build | Block the build and restore package wiring | Package maintainer |
+
+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.

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

@@ -18,10 +18,20 @@ MariaDB, MongoDB, Redis, Elasticsearch/OpenSearch, MinIO, RabbitMQ, Memcached, C
 
 Разрешено ровно два состояния: публикации нет, либо она привязана к петле (`127.0.0.1` или `::1`).
 
-**Почему это правило №0, а не пожелание.** Тестовый Postgres, поднятый с `-p 55432:5432` и паролем
-`postgres`, был взломан из интернета примерно за час: через `COPY … TO PROGRAM` на машину въехал
-червь-майнер. Порт был открыт «на время отладки». Цена ошибки здесь — компрометация машины, а не
-неудобство, поэтому правило безусловное.
+**Почему это правило №0, а не пожелание.** Одна и та же внешняя публикация создаёт две разные угрозы
+в зависимости от механики аутентификации хранилища:
+
+- **Класс A — Postgres, MySQL, MariaDB, MongoDB.** Наблюдаемый внешний binding открывает сервер для
+  попыток входа: слабый или подобранный пароль вместе с возможностями сервера может привести к
+  компрометации. Измеренный случай — тестовый Postgres с паролем `postgres`, взломанный примерно за
+  час; через `COPY … TO PROGRAM` на машину въехал червь-майнер.
+- **Класс B — Redis, Valkey, KeyDB, Memcached.** Наблюдаемый внешний binding опаснее не из-за
+  стойкости пароля: образ этого класса по умолчанию не требует пароля, поэтому публикация сразу даёт
+  доступ без аутентификации.
+
+Для обоих классов действие одно: убрать `ports:` и обращаться к хранилищу по имени в compose-сети.
+Порт был открыт «на время отладки», но цена ошибки здесь — компрометация машины, а не неудобство,
+поэтому правило безусловное.
 
 ## Что писать вместо
 
@@ -77,29 +87,41 @@ rate-limiting, заголовки. Известный конкретный сл
 ## Чем это правило НЕ является
 
 **Проверка теперь есть — но она не запускается сама.** В пакете отгружается
-`.claude/hooks/check-ports.cjs`: он читает нормализованный конфиг (`docker compose config`) и
-проверяет ровно этот инвариант, включая `network_mode: host` и обход reverse-proxy.
+`.claude/hooks/check-ports.cjs` с двумя разными, намеренно выбираемыми областями:
 
 ```bash
-node .claude/hooks/check-ports.cjs .          # или путь к конкретному compose-файлу
+node .claude/hooks/check-ports.cjs .          # каталог: один compose-проект
+node .claude/hooks/check-ports.cjs --machine  # снимок running-контейнеров текущего Docker-контекста
 ```
 
-Коды возврата — три, и третий здесь главный: `0` правило соблюдено, `1` нарушено, **`2` проверка НЕ
-ВЫПОЛНЕНА** (нет compose, нет docker, конфиг не читается). Проверка, которая на нечитаемом конфиге
+Каталоговый режим читает нормализованный конфиг (`docker compose config`) одного проекта, включая
+`network_mode: host` и обход reverse-proxy, но никогда не опрашивает running-контейнеры. Режим
+`--machine` перечисляет распознанные запущенные хранилища текущего Docker-контекста, смотрит их живые
+bindings/Compose-метки и только там проверяет runtime-аутентификацию Redis. Это снимок в момент ручного
+запуска, не непрерывный мониторинг и не утверждение о stopped-контейнерах или другом Docker context.
+
+Для Redis/Memcached каталог отдельно проверяет видимую auth-конфигурацию: доказанное отсутствие
+пароля даёт `1`, а volume/custom image, способный скрывать конфиг, — `2`, не ложный `0`. Существующее
+исключение применяется раньше этой проверки: cache, опубликованный **только на loopback**, остаётся
+разрешённым в каталоге; его фактическое беспарольное состояние обнаруживает только `--machine`.
+
+Коды возврата — три, и третий здесь главный: `0` выбранная область проверена и нарушение не найдено,
+`1` найдено доказанное нарушение, **`2` проверка НЕ ВЫПОЛНЕНА** полностью (нет compose/docker/прав,
+конфиг или обязательный runtime probe не дают ответа). Проверка, которая на неизвестном состоянии
 отвечает «чисто», хуже отсутствия проверки: она превращает неизвестность в заверение.
 
-**Чего она НЕ делает.** Она не привязана ни к какому событию — её надо позвать. Она смотрит на ВАШ
-проект, а не на машину: конфликты с портами, уже занятыми другими контейнерами, она не ищет. И она
-проверяет конфиг, а не запущенный стек.
+**Чего не доказывает каталоговая квитанция. ЭКСПОЗИЦИЯ:** соседний проект на этой же машине может
+держать хранилище открытым в интернет, а каталоговая проверка вашего проекта всё равно ответит `0`.
+Для ответа о распознанных running-хранилищах всей машины отдельно вызывайте `--machine`; и этот ответ
+ограничен снимком текущего Docker-контекста в момент запуска.
 
-Детерминированная проверка существует отдельно (`check-port-conflicts.sh`, «Правило №0») и в этот
-пакет не входит. Причина: она на bash, а ХУКИ пакета принципиально на кросс-платформенном Node —
-ради Windows, — и проверка портов по форме именно хук. (Точности ради: пара вспомогательных `.sh`
-в пакете уже есть, внутри навыка `brutal-honesty-review`; обещание Node относится к хукам, а не ко
-всему пакету.) Если проверка вам нужна, её надо взять и подключить осознанно.
+Левая часть `${DB_PORT:-11432}:5432` задаёт значение `HOST_PORT`, но ничего не говорит об адресе
+публикации. Адрес появляется только в трёхчастной форме
+`HOST_IP:HOST_PORT:CONTAINER_PORT`. Если `HOST_IP` опущен, Docker по умолчанию публикует на
+`0.0.0.0` — то есть на все интерфейсы (и может также создать IPv6 binding на `::`).
 
-Не выводите из присутствия этого правила, что кто-то за вас смотрит. Пока проверки нет, единственный
-контроль — глаза на ревью, и знать об этом важнее, чем иметь правило.
+**Чего она НЕ делает.** Она не привязана ни к какому событию — её надо позвать. Не выводите из
+присутствия правила или последней зелёной квитанции, что кто-то продолжает смотреть за машиной.
 
 ## Быстрая самопроверка