@dzhechkov/harness-core 0.8.38 → 0.8.40

package/src/mutation-gate.ts

@@ -494,6 +494,12 @@ export interface MutationObservation {
   readonly outputError?: string;
   /** bounded log proving an internal runner failure received at most one retry. */
   readonly internalAttemptLog?: string;
+  /**
+   * Whether any suite the entry's `testCommand` selects NAMES the mutated module — see
+   * {@link suiteSelectionNamesModule}. Only read on the UNDEFENDED path, and only to add a hint:
+   * `false` says "check the command before the tests", never "the property is fine".
+   */
+  readonly suiteNamesModule?: boolean | 'unknown';
 }
 
 export interface MutationEntryResult {
@@ -1333,7 +1339,13 @@ function classifyMutationOutcomeWithoutAttemptLog(obs: MutationObservation): Mut
       applied: true,
       verdict: 'UNDEFENDED',
       drop: false,
-      detail: `suite stayed GREEN with the protection deleted — property UNDEFENDED: "${e.property}" (${e.file}). The suite would not notice this protection regressing (rule 2).`,
+      detail: `suite stayed GREEN with the protection deleted — property UNDEFENDED: "${e.property}" (${e.file}). The suite would not notice this protection regressing (rule 2).`
+        + (obs.suiteNamesModule === false
+          ? ' HINT: no suite in this entry\'s testCommand NAMES this module, so check the COMMAND before the tests'
+            + ' — a suite that never loads the module cannot notice its protection (MEASURED 2026-09-04: two properties'
+            + ' read as UNDEFENDED for exactly this reason, and both tests existed). The hint matches the module stem,'
+            + ' so a transitive import would not be seen by it: it narrows where to look, it does not decide.'
+          : ''),
     };
   }
 
@@ -1408,6 +1420,47 @@ function classifyMutationOutcomeWithoutAttemptLog(obs: MutationObservation): Mut
   };
 }
 
+/**
+ * Suite paths a registry `testCommand` selects, in order. Tokens that are not suite files (the
+ * runner, its flags) are ignored — the command is a shell line, not a schema, so this reads the
+ * shape it actually has rather than assuming one.
+ */
+export function parseSuitePaths(testCommand: string): readonly string[] {
+  return String(testCommand ?? '')
+    .split(/\s+/)
+    .filter((token) => /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(token) && !token.startsWith('-'));
+}
+
+/**
+ * Does ANY suite the command selects even name the mutated module?
+ *
+ * Why this exists: `UNDEFENDED` reads as "this property has no test", and MEASURED 2026-09-04 that
+ * reading was wrong twice in one run — both tests existed; the registry's `testCommand` simply did
+ * not select the suites that import them (backlog 1f4e4f66). The author filed a finding about two
+ * "unprotected properties" before checking the instrument, which is the failure this hint prevents.
+ *
+ * Deliberately a HINT, never a verdict: it matches the module's STEM in each suite's text, so a
+ * suite that reaches the module through a transitive import is invisible to it. `'unknown'` when no
+ * suite could be read — absence of evidence is not evidence, and a hint that guesses is worse than
+ * no hint.
+ */
+export function suiteSelectionNamesModule(input: {
+  readonly file: string;
+  readonly suitePaths: readonly string[];
+  readonly readSuite: (path: string) => string | null;
+}): boolean | 'unknown' {
+  const stem = String(input.file ?? '').split('/').pop()?.replace(/\.[cm]?[jt]sx?$/, '') ?? '';
+  if (stem === '') return 'unknown';
+  let read = 0;
+  for (const suite of input.suitePaths) {
+    const text = input.readSuite(suite);
+    if (text === null) continue;
+    read += 1;
+    if (text.includes(stem)) return true;
+  }
+  return read === 0 ? 'unknown' : false;
+}
+
 export function classifyMutationOutcome(obs: MutationObservation): MutationEntryResult {
   const result = classifyMutationOutcomeWithoutAttemptLog(obs);
   if (obs.internalAttemptLog === undefined) return result;
@@ -1488,6 +1541,65 @@ export function summarizeMutationResults(results: readonly MutationEntryResult[]
   };
 }
 
+// ── Durable verdicts (instrument-round-b T3/FR-3/A3/A4, ADR-001 D3) ────────────────────────────
+//
+// The registry (`test/mutation-registry.json`) is the gate's INPUT — what to mutate. A verdict is
+// its OUTPUT — what happened the last time the gate ran. Mixing them means the input would change
+// on every run and every reader of the registry (mutation-registry-freshness included) would have
+// to start tolerating a moving file; A4 keeps them apart on purpose. `dz mutation-gate` (the CLI
+// executor) appends one JSON line per classified entry to a SEPARATE durable file
+// (`.dz/mutation-gate/verdicts.jsonl`) so a verdict survives the executor's own scratch-dir
+// teardown and the host's next reboot — today it lives only in `DZ_MUTGATE_OUTPUT_DIR`, a temp
+// directory (00_complexity_assessment.md: 0 of 377 registry entries carry a persisted verdict).
+
+/** Everything the CLI knows that this pure module does not: when, in which package, and under
+ *  which run. `runId` is honest-absent (`null`) when the caller has none to offer — never guessed. */
+export interface MutationVerdictMeta {
+  readonly ts: string;
+  readonly package: string;
+  readonly runId: string | null;
+}
+
+/** One durable line — append-only, one per classified registry entry. `observed` is the
+ *  registry's OWN anchor (copied, never recomputed) so a reader can see the historical coverage
+ *  claim next to the fresh verdict without re-opening the registry. */
+export interface MutationVerdictRow {
+  readonly ts: string;
+  readonly package: string;
+  readonly entryId: string;
+  readonly verdict: MutationVerdict;
+  readonly failingCount: number | null;
+  readonly observed: number | null;
+  readonly drop: boolean;
+  readonly dropComparable: boolean;
+  readonly runId: string | null;
+}
+
+/**
+ * Pure: payload in, row out — no filesystem (NFR-2; the CLI owns the append). `entry` is `null`
+ * for a result that never resolved to a valid registry entry (`ENTRY_INVALID` / `COVERAGE_GAP` —
+ * `parseMutationRegistry` excludes those from `registry.entries` by construction, so the CALLER
+ * cannot always hand one in) — `observed` then stays `null`, honestly, rather than the caller
+ * inventing a fallback entry object just to satisfy this signature.
+ */
+export function mutationVerdictRow(
+  entry: MutationRegistryEntry | null,
+  result: MutationEntryResult,
+  meta: MutationVerdictMeta,
+): MutationVerdictRow {
+  return {
+    ts: meta.ts,
+    package: meta.package,
+    entryId: result.id,
+    verdict: result.verdict,
+    failingCount: result.failingCount,
+    observed: entry !== null && typeof entry.observed === 'number' ? entry.observed : null,
+    drop: result.drop,
+    dropComparable: result.dropComparable,
+    runId: meta.runId,
+  };
+}
+
 const VERDICT_MARK: Record<MutationVerdict, string> = {
   PROVEN: '✓',
   ENTRY_INVALID: '✗',

package/src/name-check.ts

@@ -127,7 +127,37 @@ export function decideNameCheck(queries: readonly NameQuery[], facts: NameFacts)
   return { outcome: 'free', exit: 0, results, reason: `all ${results.length} name(s) are free` };
 }
 
-export function renderNameCheck(decision: NameDecision, scanned?: NameFacts['scanned']): string[] {
+/**
+ * Имена того же вида, ДЕЛЯЩИЕ СЛОВО с запрошенным.
+ *
+ * ЗАЧЕМ ЭТО ЗДЕСЬ. `name-check` отвечает на вопрос «занято ли ИМЯ», и отвечает верно. Но у
+ * него есть соседний вопрос, которого он не задаёт: «а нет ли уже ПРИБОРА для этой работы».
+ * ИЗМЕРЕНО 2026-09-19: `dz name-check --module ledger-cost-fill` честно ответил FREE, и по
+ * этому ответу был построен модуль, дублирующий существующий `ledger-backfill` — подключённый
+ * к CLI, с тем же измерением в шапке, заполняющий 47 строк против 31 у дубля и вдобавок
+ * намеренно НЕ делающий того, что дубль сделал (вывод минут и агентов, тихо переопределивший
+ * две колонки).
+ *
+ * Поэтому здесь НЕ вердикт и НЕ отказ — свободное имя остаётся свободным. Это СВЕДЕНИЯ в точке
+ * решения: список соседей по корню слова, которые оператор увидит ровно тогда, когда ещё не
+ * написал ни строки. Разница между «занято» и «рядом есть похожее» сохранена намеренно:
+ * превратить второе в отказ значило бы запретить `publish-order` рядом с `publish-signing`.
+ *
+ * Слова короче четырёх букв игнорируются: `fa`, `dz`, `to`, `run` роднят почти всё со всем.
+ */
+export function nearNames(query: NameQuery, facts: NameFacts, limit = 5): string[] {
+  const words = (n: string): string[] =>
+    n.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 4);
+  const asked = new Set(words(query.name));
+  if (asked.size === 0) return [];
+  const pool: string[] = query.kind === 'command'
+    ? [...facts.commands]
+    : query.kind === 'module' ? [...facts.modules.keys()] : [...facts.exports.keys()];
+  const hits = pool.filter((n) => n !== query.name && words(n).some((w) => asked.has(w)));
+  return hits.sort().slice(0, limit);
+}
+
+export function renderNameCheck(decision: NameDecision, scanned?: NameFacts['scanned'], facts?: NameFacts): string[] {
   const out: string[] = [];
   if (scanned !== undefined) {
     // Printed always, pass or fail: the operator must be able to see that the sweep looked at a real
@@ -145,6 +175,18 @@ export function renderNameCheck(decision: NameDecision, scanned?: NameFacts['sca
     // Said on the passing path, because that is where the limit gets forgotten: the scan reads
     // declarations, so a re-export under a different name (`export { a as b }`) is invisible to it.
     out.push('  note: this reads declarations in source. A re-export under a different name is not visible here — the build still owns that case.');
+    if (facts !== undefined) {
+      // Свободное имя — не доказательство отсутствия прибора. Соседи печатаются СВЕДЕНИЯМИ,
+      // вердикт при этом не меняется: отказывать за сходство значило бы запретить
+      // `publish-order` рядом с `publish-signing`.
+      for (const r of decision.results) {
+        const near = nearNames({ kind: r.kind, name: r.name }, facts);
+        if (near.length > 0) {
+          out.push(`  рядом уже есть ${r.kind}(s), делящие слово с «${r.name}»: ${near.join(', ')}`);
+          out.push('    прочитайте их ПЕРЕД тем, как писать: свободное ИМЯ не означает отсутствия ПРИБОРА для этой работы');
+        }
+      }
+    }
   }
   return out;
 }

package/src/no-stubs.ts

@@ -118,6 +118,8 @@ export interface StubFinding {
   readonly detail: string;
 }
 
+import { maskMarkdown } from './markdown-masker.js';
+
 /** A config waiver: path-keyed, reason MANDATORY. A reasonless entry is refused, never honoured. */
 export interface StubWaiver {
   readonly path?: string;
@@ -141,18 +143,25 @@ function maskInlineCode(line: string): string {
  * clean, while a naked stub line in doc prose still fires. Code files are scanned in full: a marker
  * a code file must legitimately carry (another gate's source, a fixture) takes an inline
  * `no-stubs: <reason>` waiver — visible, reasoned, greppable.
+ *
+ * Block scoping is DELEGATED to the canonical masker, not re-implemented here. The hand-rolled
+ * `inFence = !inFence` toggle it replaces broke two CommonMark rules and produced MEASURED false
+ * positives (2026-09-20): a fence closes only on its OWN marker, so a `~~~` line inside a backtick
+ * block is content — the toggle read it as a close and scanned the rest of the code block as prose;
+ * and a closing fence may carry NO info string, so a second info-string line closed the block.
+ * `unclosed: 'hide'` preserves THIS reader's existing policy — an unclosed opener hides the tail
+ * rather than restoring it, because a gate must not invent findings out of a half-written block.
+ * Four-space indented code stays unmasked (the masker default): unchanged from the toggle era, a
+ * known limit rather than a new one.
  */
 export function scanStubs(path: string, text: unknown): StubFinding[] {
   if (typeof text !== 'string' || text.length === 0) return [];
   const md = isMarkdown(path);
   const out: StubFinding[] = [];
-  let inFence = false;
   const lines = text.split('\n');
+  const scanLines = md ? String(maskMarkdown(text, { unclosed: 'hide' })).split('\n') : lines;
   for (let i = 0; i < lines.length; i++) {
-    const raw = lines[i]!;
-    if (md && /^\s*(```|~~~)/.test(raw)) { inFence = !inFence; continue; }
-    if (md && inFence) continue;
-    const line = md ? maskInlineCode(raw) : raw;
+    const line = md ? maskInlineCode(scanLines[i] ?? '') : lines[i]!;
 
     // Inline waiver first: with a reason ⇒ the line is exempt; without one ⇒ refuse loudly AND
     // leave the marker finding in place (a refused waiver must not half-work).

package/src/operations.ts

@@ -8,7 +8,7 @@
 
 import { execFileSync, spawnSync, type SpawnSyncOptionsWithStringEncoding } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -51,6 +51,7 @@ import { WINDSURF_RULES_ROOT } from '@dzhechkov/adapter-windsurf';
 import { AGENTS_MD_BLOCK_BEGIN, mergeAgentsMd, mergeGeminiMd, mergePolicyBlock, renderAgentsMdSection } from '@dzhechkov/core';
 import type { CanonicalSkill, EmitResult, SkillAsset } from '@dzhechkov/core';
 import { computeRiskScore } from './risk-scoring.js';
+import { checkInstrumentFreshness, checkRankingState } from './doctor-instrument.js';
 
 import { applyEmitResult } from './apply.js';
 import { describeSkillLoadFailure, discoverSkillIds, loadSkillFromDir } from './skills.js';
@@ -1039,6 +1040,12 @@ export function runMigrate(options: { projectRoot: string }): MigrateReport {
 export interface DoctorCheck {
   readonly name: string;
   readonly ok: boolean;
+  /**
+   * Rendering severity for a check that is NOT a failure. `warn` = measured and worth saying out
+   * loud; `unknown` = the evidence could not be gathered, which is never rendered as a pass. Neither
+   * value participates in `DoctorReport.ok`, so neither can change any caller's exit code.
+   */
+  readonly level?: 'warn' | 'unknown';
   readonly detail: string;
 }
 
@@ -1050,7 +1057,13 @@ export interface DoctorReport {
 }
 
 /** Report environment diagnostics for the harness. */
-export async function runDoctor(options: { projectRoot: string }): Promise<DoctorReport> {
+/**
+ * `instrumentPath` is the executable that is answering — normally the CLI's own `process.argv[1]`.
+ * It is an INPUT, not something this module reads for itself: `core-boundary` rule A forbids core
+ * from touching process globals, because core is a library and the process belongs to whoever hosts
+ * it. Omitted ⇒ the instrument-freshness check honestly reports that it could not tell.
+ */
+export async function runDoctor(options: { projectRoot: string; instrumentPath?: string | null }): Promise<DoctorReport> {
   const checks: DoctorCheck[] = [];
   const root = options.projectRoot;
 
@@ -1065,6 +1078,74 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
   // monorepo (or a fork of it) and owes itself these checks; anything else is a consumer project
   // and gets a NAMED skip — a skip, never a silent pass and never a fail.
   const isMonorepo = existsSync(join(root, 'packages', '@dzhechkov'));
+
+  // The executable is part of the measurement. Resolve the CALLER-SUPPLIED path (including its
+  // symlinks), then attribute it to the nearest package.json. Every read is independent and
+  // fail-quiet so a broken install becomes an explicit UNKNOWN diagnostic instead of throwing.
+  let binPath: string | null = null;
+  try {
+    const given = options.instrumentPath;
+    binPath = given === undefined || given === null ? null : realpathSync(given);
+  } catch { /* unresolved is reported by the pure decider */ }
+  let binVersion: string | null = null;
+  if (binPath !== null) {
+    try {
+      let cursor = dirname(binPath);
+      while (true) {
+        const packagePath = join(cursor, 'package.json');
+        if (existsSync(packagePath)) {
+          const parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as { version?: unknown };
+          binVersion = typeof parsed.version === 'string' ? parsed.version : null;
+          break;
+        }
+        const parent = dirname(cursor);
+        if (parent === cursor) break;
+        cursor = parent;
+      }
+    } catch { binVersion = null; }
+  }
+  let treeVersion: string | null = null;
+  if (isMonorepo) {
+    try {
+      const parsed = JSON.parse(readFileSync(join(root, 'packages', '@dzhechkov', 'harness-cli', 'package.json'), 'utf8')) as { version?: unknown };
+      treeVersion = typeof parsed.version === 'string' ? parsed.version : null;
+    } catch { treeVersion = null; }
+  }
+  let realRoot = resolvePath(root);
+  let realRootResolved = true;
+  // A root that cannot be resolved through its symlinks makes the containment question undecidable
+  // rather than false — the decider is told so explicitly instead of silently comparing two path
+  // forms that need not agree.
+  try { realRoot = realpathSync(root); } catch { realRootResolved = false; }
+  const instrument = checkInstrumentFreshness({ binPath, binVersion, treeVersion, projectRoot: realRoot, projectRootRealpathed: realRootResolved, isMonorepo });
+  checks.push({
+    name: 'doctor instrument freshness',
+    // The pure decider owns the verdict; this wiring only carries it. Never re-derive `ok` here.
+    ok: true,
+    ...(instrument.level === 'ok' ? {} : { level: instrument.level }),
+    detail: instrument.detail,
+  });
+
+  const rankingStatePath = join(realRoot, '.dz', 'lesson-bandit', 'state.json');
+  let rankingFlagOn = false;
+  try {
+    const parsed = JSON.parse(readFileSync(join(root, '.dz', 'config.json'), 'utf8')) as {
+      memory?: { learning?: { banditRerank?: unknown } };
+    };
+    rankingFlagOn = parsed.memory?.learning?.banditRerank === true;
+  } catch { /* malformed config is owned by the config diagnostic; ranking defaults off */ }
+  const ranking = checkRankingState({
+    flagOn: rankingFlagOn,
+    statePath: rankingStatePath,
+    stateExists: existsSync(rankingStatePath),
+    binPath,
+  });
+  checks.push({
+    name: 'bandit ranking state',
+    ok: true,
+    ...(ranking.level === 'warn' ? { level: 'warn' as const } : {}),
+    detail: ranking.detail,
+  });
   checks.push({
     name: '.claude/skills present',
     ok: existsSync(join(root, '.claude', 'skills')),
@@ -1648,7 +1729,8 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
       const text = readFileSync(p, 'utf-8');
       const v = verifyEventChainText(text);
       if (v.chained === 0 || v.ok) continue;
-      const total = text.split('\n').filter((l) => l.trim() !== '').length;
+      // The verifier already counted non-empty lines; re-deriving it drifts (see cli.ts note).
+      const total = v.lines;
       const age = classifyChainDefects(v, total);
       const named = `${v.defects.length} defect(s): ${v.defects.slice(0, 3).map((d) => `${d.kind}@L${d.line}`).join(', ')}`;
       // A break that an unbroken run has already outlived is not a reason to distrust today's

package/src/patterns.ts

@@ -755,10 +755,52 @@ export async function reinforcePattern(projectRoot: string, dzIdOrText: string,
   return result;
 }
 
+/**
+ * Which learned pattern does `--reinforce <arg>` mean? PURE, so the branch that REFUSES has a test.
+ *
+ * Order: the full id, then the exact text, then a BARE id suffix.
+ *
+ * The suffix step exists because an id is PRINTED as `<namespace>:<suffix>` — `teach:1a4a9bdd…` —
+ * by every surface that emits one (`dz teach`'s own `ID:` line, `dz recall --json`'s `dzId`), and a
+ * caller who kept only the hex got `no learned pattern matches`. The advisory then pointed at
+ * `dz recall`, which cannot surface a QUARANTINED lesson by its own text, so a lesson taught
+ * minutes ago had no reachable path at all (MEASURED 2026-09-20, backlog 2d3059fc). The report's
+ * wider claim — that ids are rejected outright — is REFUTED: the full printed id has always worked.
+ *
+ * An ambiguous suffix is refused BY NAME, never guessed. Reinforcing the wrong lesson writes
+ * silently and leaves no signal afterwards that the wrong record moved, so a wrong guess here is
+ * strictly worse than a refusal the caller can act on. Today only `teach:` ids exist, but `dream:`
+ * is a second canonical namespace this store already documents, so the collision is reachable.
+ */
+export function resolveReinforceTarget(
+  records: readonly MemoryRecord[],
+  dzIdOrText: string,
+): { rec: MemoryRecord; matchedBy: 'id' | 'text' | 'suffix' } | { rec: undefined; error: string } {
+  // The KIND of match is part of the answer, not a detail: the caller prints it in a receipt, and a
+  // receipt that says "matched by text" about a suffix match is a receipt that lies. MEASURED
+  // 2026-09-20: the CLI inferred the kind from `resolved !== input`, which is true for BOTH a text
+  // match and a suffix match, so the suffix path reported the wrong one.
+  const byId = records.find((r) => r.id === dzIdOrText);
+  if (byId !== undefined) return { rec: byId, matchedBy: 'id' };
+  const byText = records.find((r) => r.text === dzIdOrText);
+  if (byText !== undefined) return { rec: byText, matchedBy: 'text' };
+  const bare = records.filter((r) => typeof r.id === 'string' && r.id.endsWith(':' + dzIdOrText));
+  if (bare.length > 1) {
+    return {
+      rec: undefined,
+      error: `${JSON.stringify(dzIdOrText)} is a bare id suffix shared by ${bare.length} learned patterns (${bare.map((r) => r.id).join(', ')}) — pass the full id`,
+    };
+  }
+  const only = bare[0];
+  if (only !== undefined) return { rec: only, matchedBy: 'suffix' };
+  return { rec: undefined, error: `no learned pattern matches ${JSON.stringify(dzIdOrText)}` };
+}
+
 async function reinforcePatternLocked(projectRoot: string, dzIdOrText: string, opts: { reward?: number; ts?: string; mergedFrom?: readonly string[]; exposure?: boolean }): Promise<ReinforcePatternResult> {
   const records = loadStoreRecords(projectRoot);
-  const rec = records.find((r) => r.id === dzIdOrText || r.text === dzIdOrText);
-  if (rec === undefined) return { ok: false, error: `no learned pattern matches ${JSON.stringify(dzIdOrText)}` };
+  const resolved = resolveReinforceTarget(records, dzIdOrText);
+  if (resolved.rec === undefined) return { ok: false, error: resolved.error };
+  const rec = resolved.rec;
   const pairId = typeof rec.metadata?.['lessonPairId'] === 'string' ? rec.metadata['lessonPairId'] : undefined;
   const targets = pairId === undefined
     ? [rec]
@@ -781,14 +823,14 @@ async function reinforcePatternLocked(projectRoot: string, dzIdOrText: string, o
   for (const target of targets) {
     const promotedMeta = { ...(target.metadata ?? {}), ...encodeReinforcementState(nextState) };
     if (opts.exposure !== true) {
-      delete promotedMeta['qStatus'];
-      delete promotedMeta['quarantinedAt'];
+      promotedMeta['qStatus'] = 'promoted';
+      promotedMeta['promotedAt'] = ts;
     }
     const put = await putStoreRecord(projectRoot, { ...target, metadata: promotedMeta });
     if ('error' in put) return { ok: false, dzId: rec.id, error: put.error };
   }
   try {
-    appendFileSync(join(projectRoot, '.dz', 'sessions.jsonl'), JSON.stringify({ event: 'reinforce', ts, dzId: rec.id, uses: nextState.uses }) + '\n');
+    appendFileSync(join(projectRoot, '.dz', 'sessions.jsonl'), JSON.stringify({ event: 'reinforce', ts, dzId: rec.id, uses: nextState.uses, exposure: opts.exposure === true }) + '\n');
   } catch { /* best-effort */ }
   return { ok: true, dzId: rec.id, uses: nextState.uses, reward: observed };
 }
@@ -845,10 +887,9 @@ export async function promotePatterns(projectRoot: string, dzIds: readonly strin
         const targets = pairId === undefined ? [rec] : records.filter((r) => r.metadata?.['lessonPairId'] === pairId);
         const pending = targets.filter((target) => !handled.has(target.id) && readQuarantineState(target).quarantined);
         if (pending.length === 0) { notQuarantined.push(id); continue; }
+        const promotedAt = new Date().toISOString();
         for (const target of pending) {
-          const meta = { ...(target.metadata ?? {}) };
-          delete meta['qStatus'];
-          delete meta['quarantinedAt'];
+          const meta = { ...(target.metadata ?? {}), qStatus: 'promoted', promotedAt };
           const put = await putStoreRecord(projectRoot, { ...target, metadata: meta });
           if ('error' in put) return { ok: false, promoted, notFound, notQuarantined, error: put.error };
           handled.add(target.id);

package/src/publish-source-scope.ts

@@ -0,0 +1,53 @@
+/**
+ * Что считается ПУБЛИКУЕМЫМ ИСХОДНИКОМ для гейта review-round.
+ *
+ * ЗАЧЕМ ЭТО ВЫНЕСЕНО. Правило `review-round` — единственный жёсткий гейт, спрашивающий, читал ли
+ * изменённый код кто-то, кроме автора. Его сборщик фактов жил одной строкой в `cli.ts` и помечал
+ * изменение исходником только по пути `^(src|lib|bin|skills)/`.
+ *
+ * ИЗМЕРЕНО (запись 5be1bee1, релиз 2026-08-25): пак навыков возит своё содержимое из `templates/`
+ * и `<имя-навыка>/`, поэтому `skills-feature-adr` мог поднять версию, изменить сам конвейер
+ * `templates/.claude/workflows/feature-adr.js` и гейт `feature-adr/scripts/*.mjs` — и правило НЕ
+ * СРАБАТЫВАЛО, а гейт печатал PASS. То есть пакеты, несущие ВЕСЬ конвейер, лежали вне
+ * единственной проверки на прочитанность. Страж, который не может сработать, хуже отсутствующего:
+ * он создаёт видимость защиты.
+ *
+ * ПОЧЕМУ НЕ «ВСЁ, ЧТО ПУБЛИКУЕТСЯ». Комментарий прежней строки защищал осознанное решение:
+ * «SOURCE = то, что ОТГРУЖАЕТСЯ и может ОШИБИТЬСЯ В РАНТАЙМЕ. Тесты, документация и фикстуры
+ * исключены… расширение области — это то, из-за чего жёсткий гейт выключают». Взять список
+ * публикуемых файлов целиком значило бы затянуть в гейт всю документацию пака и вернуть ровно ту
+ * переусердствующую форму, от которой это решение защищает.
+ *
+ * ПОЭТОМУ КРИТЕРИЙ — ИСПОЛНИМОСТЬ, А НЕ РАСПОЛОЖЕНИЕ: файл считается исходником, если он либо
+ * лежит в одном из исторических каталогов, либо ИСПОЛНЯЕТСЯ у потребителя по своему расширению —
+ * где бы он ни лежал. Документация, данные и тесты исключены в обоих случаях.
+ */
+
+/** Каталоги, чьё содержимое отгружается, но исходником для этого гейта не считается. */
+const NOT_SOURCE_DIR = /(^|\/)(test|tests|__tests__|fixtures|__fixtures__|dist|node_modules|coverage)(\/|$)/;
+
+/** Исторические каталоги исходников — сохранены дословно, чтобы поведение не поехало. */
+const LEGACY_SOURCE_DIR = /^(src|lib|bin|skills)\//;
+
+/** Расширения, которые исполняются у потребителя. Разметка и данные сюда НЕ входят. */
+const EXECUTABLE_EXT = /\.(?:[cm]?js|[cm]?ts|sh|bash|py)$/;
+
+/** Расширения, которые исторически исключались даже внутри каталогов исходников. */
+const NEVER_SOURCE_EXT = /\.(?:md|json|txt|yaml|yml)$/;
+
+/**
+ * Изменение этого файла означает, что пакет отгружает НОВЫЙ ИСПОЛНЯЕМЫЙ код?
+ *
+ * @param relPath путь ВНУТРИ каталога пакета (`templates/.claude/workflows/feature-adr.js`),
+ *                а не от корня репозитория
+ */
+export function isShippedSource(relPath: string): boolean {
+  if (typeof relPath !== 'string' || relPath === '') return false;
+  const p = relPath.replace(/\\/g, '/');
+  // Порядок важен: исключение каталога сильнее любого включения, иначе `test/helper.ts`
+  // и пересобранный `dist/index.js` начали бы требовать круг ревью.
+  if (NOT_SOURCE_DIR.test(p)) return false;
+  if (NEVER_SOURCE_EXT.test(p)) return false;
+  if (LEGACY_SOURCE_DIR.test(p)) return true;
+  return EXECUTABLE_EXT.test(p);
+}

package/src/publish.ts

@@ -5,8 +5,9 @@
  * @packageDocumentation
  */
 
+import { maskMarkdown } from './markdown-masker.js';
 import { existsSync, readFileSync, writeFileSync, readdirSync, renameSync } from 'node:fs';
-import { join as pathJoin, relative as pathRelative, resolve as pathResolve } from 'node:path';
+import { join as pathJoin, relative as pathRelative, resolve as pathResolve, isAbsolute as pathIsAbsolute, sep as pathSep } from 'node:path';
 
 import { decidePublishSigning, decidePostSigningVerification } from './publish-signing.js';
 import { join } from 'node:path';
@@ -381,6 +382,24 @@ export function publishArgv(mode: ProvenanceMode, env: NodeJS.ProcessEnv): strin
   return decideProvenance(mode, env).useProvenance ? base + ' --provenance' : base;
 }
 
+/** Match substrings against package identity and path without including the checkout root. */
+export function matchesPublishFilter(
+  pkg: { name: string; dir: string },
+  filter: string,
+  monorepoRoot: string,
+): boolean {
+  const normalizedFilter = filter.replace(/\\/g, '/');
+  const relativeDir = pathRelative(pathResolve(monorepoRoot), pathResolve(pkg.dir));
+  // A foreign path must not reintroduce checkout ancestors into the match.
+  const outsideRoot = relativeDir === '..' || relativeDir.startsWith(`..${pathSep}`) || pathIsAbsolute(relativeDir);
+  // Only Windows spells separators with a backslash. On POSIX a backslash is a legal character
+  // INSIDE a directory name, so rewriting it here would invent a separator the filesystem does
+  // not have and over-select that package — the same class as the root-substring defect.
+  const comparableDir = pathSep === '\\' ? relativeDir.replace(/\\/g, '/') : relativeDir;
+  return pkg.name.includes(normalizedFilter)
+    || (!outsideRoot && comparableDir.includes(normalizedFilter));
+}
+
 /** Discover all publishable @dzhechkov packages. */
 export function discoverPackages(monorepoRoot: string): { name: string; dir: string; version: string }[] {
   const baseDir = join(monorepoRoot, 'packages', '@dzhechkov');
@@ -741,21 +760,20 @@ const REGION_END = /^ {0,3}#{1,2}\s/;
 
 /** Blank out fenced-code lines while PRESERVING line numbering, so a `## Status` or an entry-shaped
  *  line inside an example neither starts nor ends the region (the same fence blindness was found in
- *  another checker on the same day). */
+ *  another checker on the same day).
+ *
+ *  Scoping is DELEGATED to the canonical masker, not re-implemented. The local version this replaces
+ *  tracked only the marker CHARACTER and closed on any run of three or more, ignoring CommonMark's
+ *  rule that a closing fence may not be SHORTER than the opening one. MEASURED 2026-09-20: in a
+ *  README whose entry body quotes a markdown example as ````markdown … ```` , the inner ``` closed
+ *  the outer block early, the quoted `## Status` became visible, the region ENDED there, and the
+ *  body line below — `В `1.2.2` эта строка тела …` — lost protection. That is exactly the
+ *  2026-08-25 incident this function exists to stop: a record's body relabelled forward and shipped
+ *  to npm. `unclosed: 'hide'` preserves the local version's policy — an unclosed opener masks to
+ *  end of file, which is also the CommonMark reading.
+ */
 function maskFences(lines: readonly string[]): string[] {
-  const out: string[] = [];
-  let fence: string | null = null;
-  for (const line of lines) {
-    const open = /^ {0,3}(```+|~~~+)/.exec(line);
-    if (fence === null && open !== null && open[1] !== undefined) { fence = open[1][0] as string; out.push(''); continue; }
-    if (fence !== null) {
-      out.push('');
-      if (new RegExp('^ {0,3}' + fence + '{3,}\\s*$').test(line)) fence = null;
-      continue;
-    }
-    out.push(line);
-  }
-  return out;
+  return String(maskMarkdown(lines.join('\n'), { unclosed: 'hide' })).split('\n');
 }
 
 /**
@@ -883,10 +901,14 @@ export function publishPackages(
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
   });
 
+  if (opts.filter?.some((filter) => filter.length === 0)) {
+    throw new Error('publish: --filter requires non-empty package-name substrings (empty would match ALL packages)');
+  }
+
   const packages = discoverPackages(monorepoRoot);
   const results: PublishResult[] = [];
   const filtered = opts.filter && opts.filter.length > 0
-    ? packages.filter((p) => opts.filter!.some((f) => p.name.includes(f) || p.dir.includes(f)))
+    ? packages.filter((p) => opts.filter!.some((f) => matchesPublishFilter(p, f, monorepoRoot)))
     : packages;
   // Publish dependencies before dependents so pnpm rewrites workspace:* to the
   // freshly-bumped version, never a stale one (the harness-cli@0.3.122 breakage).