@dzhechkov/harness-core 0.8.39 → 0.8.40

package/src/cmd-usage.ts

@@ -153,6 +153,12 @@ interface RuleUsage {
   readonly stats: ReadonlyMap<string, CmdUsageStat>;
   readonly skipped: number;
   readonly outOfRange: number;
+  /**
+   * Audit rows inside the window that recorded which rules they EVALUATED. Zero means this report
+   * has no evidence about rules at all — which is a different answer from "the rule is unused", and
+   * the distinction is the whole point of counting it (backlog 1bee49dd).
+   */
+  readonly evaluationRows: number;
 }
 
 const REPO_BOUNDARY_IO = {
@@ -401,9 +407,13 @@ export function loadDeadwoodAllowlist(json: string): DeadwoodAllowlistEntry[] {
 function parseGuardAuditUsage(text: string, weeks: number, now: Date): RuleUsage {
   const auditTimestamps: string[] = [];
   const hits: CmdUsageInvocationRecord[] = [];
+  let evaluationRows = 0;
   let skipped = 0;
   let outOfRange = 0;
   const newestAllowed = now.getTime() + DEADWOOD_FUTURE_TOLERANCE_MS;
+  // Same window arithmetic `foldCmdUsage` uses, so "counted as evidence" and "counted as a run"
+  // cannot disagree about which rows are inside.
+  const windowStart = now.getTime() - Math.max(0, weeks) * 7 * DAY_MS;
   for (const line of text.split('\n')) {
     if (line.trim() === '') continue;
     let row: Record<string, unknown>;
@@ -425,17 +435,40 @@ function parseGuardAuditUsage(text: string, weeks: number, now: Date): RuleUsage
       continue;
     }
     auditTimestamps.push(row.ts);
+    // A rule's HEALTHY state is silence, so firing cannot measure whether it is alive. `evaluated`
+    // records the rules that actually got their turn; rows written before the field existed carry
+    // none, and they contribute evidence about firing only.
+    //
+    // Two conditions, both named by cross-family review (Codex gpt-5.6-sol, 2026-09-21), both of
+    // which turn this evidence into a false accusation if skipped:
+    //  · the row must be INSIDE the window. An instrumented row older than `now - weeks` yields no
+    //    in-window runs, so counting it as evidence would let one ancient row flip every absent
+    //    rule from "cannot judge" to "dead".
+    //  · the array must carry a USABLE id. `evaluated: []` is a row that recorded nothing; treating
+    //    it as evidence is the same false accusation by a shorter path.
+    const evaluatedIds = new Set<string>();
+    if (Array.isArray(row.evaluated)) {
+      for (const value of row.evaluated) {
+        if (typeof value === 'string' && value.trim() !== '') evaluatedIds.add(value);
+      }
+    }
+    if (evaluatedIds.size > 0 && tsMs >= windowStart) evaluationRows += 1;
+    for (const id of evaluatedIds) {
+      hits.push({ kind: 'cmd', cmd: id, ts: row.ts, v: CMD_USAGE_SCHEMA });
+    }
     const violations = Array.isArray(row.violations) ? row.violations : [];
     for (const value of violations) {
       const rule = typeof value === 'object' && value !== null
         ? (value as { rule?: unknown }).rule
         : undefined;
-      if (typeof rule === 'string' && rule.trim() !== '') {
+      // One guard run is ONE run. A rule that both evaluated and fired in the same row would be
+      // counted twice — 100 warning evaluations reported as 200 runs (same review, second finding).
+      if (typeof rule === 'string' && rule.trim() !== '' && !evaluatedIds.has(rule)) {
         hits.push({ kind: 'cmd', cmd: rule, ts: row.ts, v: CMD_USAGE_SCHEMA });
       }
     }
   }
-  return { auditTimestamps, stats: foldCmdUsage(hits, weeks, now), skipped, outOfRange };
+  return { auditTimestamps, stats: foldCmdUsage(hits, weeks, now), skipped, outOfRange, evaluationRows };
 }
 
 function timestampDepthDays(timestamps: readonly string[], now: Date): number {
@@ -607,6 +640,23 @@ export function buildDeadwoodReport(input: DeadwoodInput): DeadwoodReport {
       });
       continue;
     }
+    // A rule the window has no EVALUATION evidence for is unjudged, not unused. Firing is the wrong
+    // signal for a guard (silence is its healthy state), so without `evaluated` rows the only honest
+    // answer is "this report cannot judge the rule" — exactly what the skill surface already says.
+    if (item.kind === 'rule' && rules.evaluationRows === 0
+      && (rules.stats.get(item.surface)?.runsInWindow ?? 0) === 0
+      // An explicit allowlist entry is an operator's standing statement about this surface; it keeps
+      // its own wording. Only the ACCUSING path — "zero usage, consider deprecating" — is withdrawn.
+      && !allowlist.has(allowlistKey(item.kind, item.surface))) {
+      noInstrumentation.push({
+        state: 'no-instrumentation',
+        surface: item.surface,
+        kind: item.kind,
+        reason: 'no guard-audit row in this window recorded which rules it evaluated; a rule that '
+          + 'never fires may be a healthy safety net, so firing alone cannot judge it',
+      });
+      continue;
+    }
     classifyInstrumented(
       { surface: item.surface, kind: item.kind },
       item.kind === 'command'

package/src/compounding.ts

@@ -15,7 +15,7 @@
  * Everything here is PURE: callers gather facts (files, store rows); this module only computes.
  */
 
-import { EVENT_CHAIN_SCOPE, verifyEventChainText } from './event-chain.js';
+import { EVENT_CHAIN_SCOPE, classifyChainDefects, verifyEventChainText } from './event-chain.js';
 import {
   isOffsetIsoTimestamp,
   type PromotionAcceptanceEvidence,
@@ -160,15 +160,36 @@ export interface GuardEvent {
   readonly verdict: string;
   readonly rules: readonly string[]; // violated rule ids
   readonly violations?: readonly { readonly rule: string; readonly contentAnchor?: string }[];
+  /**
+   * 1-based position of this record among the log's non-empty lines — the ONLY thing that can place
+   * it relative to a chain defect. Absent when the caller read the rows without a chain.
+   */
+  readonly chainLine?: number;
 }
 
 export type FunnelEvidenceSource<T> =
   | { readonly status: 'measured'; readonly rows: readonly T[] }
   | { readonly status: 'not-measured'; readonly reason: string };
 
+/**
+ * Where the guard journal's chain damage sits, so a PERIOD can be judged instead of the whole FILE.
+ *
+ * A log damaged once in March and unbroken since is not evidence against September's rows, and
+ * refusing to measure September because of March is the same "verdict answers a different question"
+ * defect the chain headline was fixed for (backlog b38dd3ba, MEASURED 2026-09-21: 28 defects, all
+ * before a run of 1169 unbroken records, suppressed BOTH measured months).
+ */
+export interface GuardAuditChainWindow {
+  /** First non-empty line of the current unbroken run: one past the last defect. */
+  readonly runFrom: number;
+  /** Total defects in the file. Zero means the window imposes nothing. */
+  readonly defects: number;
+}
+
 export interface LessonToRuleFunnelFacts {
   readonly promotionRuns: FunnelEvidenceSource<PromotionRunEvidence>;
   readonly guardAudits: FunnelEvidenceSource<GuardEvent>;
+  readonly guardAuditChain?: GuardAuditChainWindow;
   readonly promotionAcceptances?: readonly PromotionAcceptanceEvidence[];
   readonly truncatedPromotionPeriods?: readonly string[];
   readonly acceptanceHistoryComplete?: boolean;
@@ -274,6 +295,20 @@ export interface EvidenceChainHealth {
   readonly preChainPrefix: number;
   readonly defects: number;
   readonly defectKinds: readonly string[];
+  /**
+   * WHERE the defects sit relative to the log's current unbroken run, and HOW MUCH of a run that is.
+   * Without this a bare `FAILED` over a log whose damage is entirely historical reads as "today's
+   * numbers are garbage", while `dz chain` over the SAME file says "healed … verdicts over those are
+   * sound" — MEASURED 2026-09-20 on `.dz/guard-audit.jsonl`: 28 defects, all before the current run,
+   * 1095 unbroken records after them; one instrument printed FAILED, the other healed, both exit 0
+   * (backlog 79ce6262). Neither was lying; neither named its WINDOW. `event-chain.ts` says it
+   * outright: a caller that reports soundness without printing the run size overclaims on its behalf,
+   * and the same holds for a caller that reports damage without printing where the damage sits.
+   */
+  readonly defectsBeforeRun: number;
+  readonly defectsInRun: number;
+  /** Records in the current unbroken run — the evidence behind any "sound for today" reading. */
+  readonly runRecords: number;
 }
 
 export interface InstrumentationHealth {
@@ -394,6 +429,13 @@ function executionMeasurement(
   if (periodAudits.length === 0) {
     return LESSON_TO_RULE_FUNNEL_POLICY.unavailable(`guard-audit-not-recorded:${period}`);
   }
+  // Damage that PRECEDES this period's rows says nothing about them; damage that touches them does.
+  // A row with no position cannot be placed, and unplaceable is not the same as sound — it refuses.
+  const chain = facts.guardAuditChain;
+  if (chain !== undefined && chain.defects > 0
+    && periodAudits.some((row) => row.chainLine === undefined || row.chainLine < chain.runFrom)) {
+    return LESSON_TO_RULE_FUNNEL_POLICY.unavailable(`guard-audit-chain-damaged:${period}`);
+  }
   const audits = periodAudits.filter((row) => row.op === 'publish');
   if (audits.length === 0) {
     return LESSON_TO_RULE_FUNNEL_POLICY.unavailable(`guard-publish-not-recorded:${period}`);
@@ -594,6 +636,11 @@ export function assembleCompoundingReport(facts: CompoundingFacts): CompoundingR
       preChainPrefix: v.preChainPrefix,
       defects: v.defects.length,
       defectKinds: [...new Set(v.defects.map((d) => d.kind))],
+      ...((age) => ({
+        defectsBeforeRun: age.beforeRun.length,
+        defectsInRun: age.inRun.length,
+        runRecords: age.runRecords,
+      }))(classifyChainDefects(v, v.lines)),
     };
   });
 
@@ -623,13 +670,7 @@ export function assembleCompoundingReport(facts: CompoundingFacts): CompoundingR
     trajectory.length > 0 ? `guard: ${improvedRules}/${trajectory.length} rules recur less in the later half` : 'guard: not enough history',
     `cold-vs-warm: ${replay.verdict === 'insufficient-data' ? 'INSUFFICIENT DATA (accruing)' : 'READY to measure'}`,
     instrumentation.applyLegLive ? 'apply leg: live' : 'apply leg: STALE — fix the instrumentation before trusting anything above',
-    ...(chains.length === 0
-      ? []
-      : [
-          instrumentation.chainsOk
-            ? 'evidence chain: verified'
-            : 'evidence chain: CORRUPT — the numbers above are computed from a damaged log',
-        ]),
+    ...(chains.length === 0 ? [] : [chainHeadline(chains)]),
   ].join(' · ');
 
   return { pool, guardTrajectory: trajectory, replay, instrumentation, lessonToRuleFunnel, verdict };
@@ -671,6 +712,68 @@ function renderFunnelPeriodMeasurements(row: LessonToRuleFunnelPeriod): string {
   return `${renderPromotionMeasurements(row)} · ${renderFunnelMeasurement('executions', row.executions)}`;
 }
 
+/**
+ * The HEADLINE verdict over every evidence log — three-valued, because two values lied.
+ *
+ * MEASURED 2026-09-21 on `.dz/guard-audit.jsonl`: 28 defects, the LAST of them dated 2026-09-05,
+ * followed by more than a thousand unbroken records. The old headline read
+ * "CORRUPT — the numbers above are computed from a damaged log", which is true of the FILE'S
+ * HISTORY and false about the numbers it was printed next to. The distinction already existed one
+ * function below, in {@link chainVerdictPhrase}; it simply never reached the line a reader sees
+ * first. That is the same defect class this report exists to find: a verdict answering a different
+ * question than the one it appears to answer.
+ */
+/**
+ * Whether the report's OWN numbers may be trusted, as a value the caller can turn into an exit code.
+ *
+ * Backlog 79ce6262 named the defect: the report printed "the numbers above are computed from a
+ * damaged log" and exited 0 anyway — a tool announcing its own output untrustworthy and reporting
+ * success. That record offered two lawful cures and asked which applies. Both do, on different
+ * branches, and only the three-valued verdict lets them coexist: damage BEHIND the current run
+ * narrows the WORDING (the numbers stand, exit 0), damage INSIDE it makes the numbers genuinely
+ * unreliable and must reach the exit code.
+ *
+ * `'trusted'` ⇒ 0. `'unreliable'` ⇒ a non-zero the caller chooses — the run succeeded, the verdict
+ * cannot be relied on, which is this repository's INCONCLUSIVE shape, not its failure shape.
+ */
+export function chainTrust(chains: readonly EvidenceChainHealth[]): 'trusted' | 'unreliable' {
+  return chains.some((c) => !c.ok && c.defectsInRun > 0) ? 'unreliable' : 'trusted';
+}
+
+export function chainHeadline(chains: readonly EvidenceChainHealth[]): string {
+  const broken = chains.filter((c) => !c.ok);
+  if (broken.length === 0) return 'evidence chain: verified';
+  const live = broken.filter((c) => c.defectsInRun > 0);
+  if (live.length === 0) {
+    const runs = broken.reduce((n, c) => n + c.runRecords, 0);
+    const defects = broken.reduce((n, c) => n + c.defects, 0);
+    return `evidence chain: damaged EARLIER — ${defects} defect(s), none inside the current run of `
+      + `${runs} unbroken record(s); the numbers above stand, the file's history does not`;
+  }
+  const inRun = live.reduce((n, c) => n + c.defectsInRun, 0);
+  return `evidence chain: CORRUPT — ${inRun} defect(s) INSIDE the current run; the numbers above are `
+    + 'computed from a damaged log';
+}
+
+/**
+ * The verdict phrase for one evidence log, with its WINDOW named. A bare `FAILED` over damage that an
+ * unbroken run has already followed is true of the FILE and misleading about TODAY — see
+ * {@link EvidenceChainHealth.defectsBeforeRun}.
+ */
+export function chainVerdictPhrase(c: EvidenceChainHealth): string {
+  if (c.ok) return 'verified';
+  const kinds = `[${c.defectKinds.join(', ')}]`;
+  if (c.defectsInRun === 0) {
+    return `DAMAGED EARLIER — ${c.defects} defect(s) ${kinds}, all BEFORE the current run of `
+      + `${c.runRecords} unbroken record(s); numbers over that run stand, the file's history does not`;
+  }
+  if (c.defectsBeforeRun === 0) {
+    return `FAILED — ${c.defects} defect(s) ${kinds} with NO sound records after them`;
+  }
+  return `FAILED — ${c.defects} defect(s) ${kinds}: ${c.defectsInRun} inside the current run of `
+    + `${c.runRecords} record(s), ${c.defectsBeforeRun} before it`;
+}
+
 export function renderCompoundingReport(r: CompoundingReport): string {
   const out: string[] = [];
   out.push('dz compounding — does the learning loop pay? (honest report: gates without data say so)');
@@ -695,7 +798,7 @@ export function renderCompoundingReport(r: CompoundingReport): string {
   );
   for (const c of r.instrumentation.chains) {
     out.push(
-      `  EVIDENCE CHAIN ${c.log}: ${c.ok ? 'verified' : `FAILED — ${c.defects} defect(s) [${c.defectKinds.join(', ')}]`}` +
+      `  EVIDENCE CHAIN ${c.log}: ${chainVerdictPhrase(c)}` +
         ` · ${c.chained} chained · ${c.preChainPrefix} pre-chain (uncovered)`,
     );
   }

package/src/doctor-instrument.ts

@@ -0,0 +1,153 @@
+import { isAbsolute, relative, sep } from 'node:path';
+
+export type InstrumentFreshness = 'same' | 'stale' | 'unknown';
+
+export interface InstrumentCheckInput {
+  /** realpath of the running binary, or null when it could not be resolved. */
+  readonly binPath: string | null;
+  /** version from the package.json that owns binPath, or null. */
+  readonly binVersion: string | null;
+  /** version from packages/@dzhechkov/harness-cli/package.json, or null outside the monorepo. */
+  readonly treeVersion: string | null;
+  /** absolute, realpath'd project root. */
+  readonly projectRoot: string;
+  /**
+   * Whether `projectRoot` above really IS realpath'd. The caller resolves it and falls back to a
+   * plain resolve when that throws; with a symlinked root that fallback compares a realpath'd
+   * binary against a non-realpath'd root, and an IN-TREE binary then looks external. Containment is
+   * undecidable in that state, so it is answered `unknown` rather than guessed either way.
+   * Named by independent review (Claude Sonnet, 2026-09-20).
+   */
+  readonly projectRootRealpathed: boolean;
+  readonly isMonorepo: boolean;
+}
+
+/**
+ * `level` is the WHOLE verdict — the caller renders it and never re-derives one of its own. That is
+ * deliberate: the first wiring of this module answered `unknown` with `ok: false` while this decider
+ * answered `ok`, and two answers to one question is the defect class this repo pays for most often.
+ *
+ * Three values, because two would lie: `ok` (the instrument is the tree's, or the check does not
+ * apply here), `warn` (measured stale — worth saying loudly, never worth failing a health command
+ * that gates other people's CI), `unknown` (the evidence could not be gathered — never rendered as
+ * a pass, and never as a failure either, since absence of evidence is not a defect).
+ */
+export interface InstrumentCheckResult {
+  readonly freshness: InstrumentFreshness;
+  readonly level: 'ok' | 'warn' | 'unknown';
+  readonly detail: string;
+}
+
+export interface RankingStateCheckInput {
+  readonly flagOn: boolean;
+  /** absolute path the state was looked for at. */
+  readonly statePath: string;
+  readonly stateExists: boolean;
+  /** resolved binary path, for the detail — null when unknown. */
+  readonly binPath: string | null;
+}
+
+/** Ranking state has no freshness concept, so it deliberately has its own result type. */
+export interface RankingStateCheckResult {
+  readonly level: 'ok' | 'warn';
+  readonly detail: string;
+}
+
+/** Strip semver build metadata: `0.8.32+a1b2c3` and `0.8.32` are the same release. */
+function withoutBuildMetadata(version: string): string {
+  const plus = version.indexOf('+');
+  return plus < 0 ? version : version.slice(0, plus);
+}
+
+function isInsideRoot(candidate: string, root: string): boolean {
+  const fromRoot = relative(root, candidate);
+  return fromRoot === '' || (!isAbsolute(fromRoot) && fromRoot !== '..' && !fromRoot.startsWith(`..${sep}`));
+}
+
+/**
+ * Decide whether the executable answering `dz doctor` is the workspace's current instrument.
+ *
+ * LIMITS NAMED BY INDEPENDENT REVIEW (Claude Sonnet, 2026-09-20), none of them hidden behind a
+ * passing test:
+ *  - Containment is a case-SENSITIVE path comparison. On a case-insensitive filesystem, or where the
+ *    same location is reachable under two path forms, an in-tree binary can read as external. This
+ *    repo runs on Linux; the cost of being wrong is one extra `warn` line and never an exit code.
+ *  - The caller attributes a version by walking up from the binary to the NEAREST `package.json`.
+ *    A shim in package A that loads package B's code is attributed to A, and a broken install with
+ *    no own manifest is attributed to whatever ancestor has one. The detail always prints the
+ *    resolved binary path so a reader can see which file was actually measured.
+ */
+export function checkInstrumentFreshness(input: InstrumentCheckInput): InstrumentCheckResult {
+  const binary = input.binPath ?? '(unresolved)';
+  const binaryVersion = input.binVersion ?? 'unknown';
+  const treeVersion = input.treeVersion ?? 'unknown';
+
+  if (!input.isMonorepo) {
+    return {
+      freshness: 'unknown',
+      level: 'ok',
+      detail: `not applicable in a consumer project: no packages/@dzhechkov tree version to compare; resolved binary ${binary}; binary version ${binaryVersion}; tree version ${treeVersion}`,
+    };
+  }
+
+  if (input.binPath !== null && input.projectRootRealpathed && isInsideRoot(input.binPath, input.projectRoot)) {
+    return {
+      freshness: 'same',
+      level: 'ok',
+      detail: `resolved binary ${input.binPath} is inside project root ${input.projectRoot}; binary version ${binaryVersion}; tree version ${treeVersion}; this binary is the tree instrument`,
+    };
+  }
+
+  if (!input.projectRootRealpathed) {
+    return {
+      freshness: 'unknown',
+      level: 'unknown',
+      detail: `project root ${input.projectRoot} could not be resolved through its symlinks, so it cannot be told whether the answering binary is the tree's own; version could not be determined safely; resolved binary ${binary}; binary version ${binaryVersion}; tree version ${treeVersion}`,
+    };
+  }
+
+  if (input.binPath === null || input.binVersion === null || input.treeVersion === null) {
+    return {
+      freshness: 'unknown',
+      level: 'unknown',
+      detail: `instrument version could not be determined; resolved binary ${binary}; binary version ${binaryVersion}; tree version ${treeVersion}`,
+    };
+  }
+
+  // Semver says build metadata after `+` does not participate in equality, so a pipeline that
+  // stamps a commit hash onto the version must not read as a stale instrument.
+  if (withoutBuildMetadata(input.binVersion) === withoutBuildMetadata(input.treeVersion)) {
+    return {
+      freshness: 'same',
+      level: 'ok',
+      detail: `resolved binary ${input.binPath}; binary version ${input.binVersion}; tree version ${input.treeVersion}; versions match`,
+    };
+  }
+
+  return {
+    freshness: 'stale',
+    level: 'warn',
+    detail: `resolved binary ${input.binPath}; binary version ${input.binVersion}; tree version ${input.treeVersion}; the answering instrument is stale`,
+  };
+}
+
+/** Decide whether enabled bandit re-ranking has the on-disk state needed to operate. */
+export function checkRankingState(input: RankingStateCheckInput): RankingStateCheckResult {
+  const binary = input.binPath ?? '(unresolved)';
+  if (!input.flagOn) {
+    return {
+      level: 'ok',
+      detail: `bandit re-ranking feature is off; no state is expected at ${input.statePath}; answering binary ${binary}`,
+    };
+  }
+  if (input.stateExists) {
+    return {
+      level: 'ok',
+      detail: `bandit re-ranking is on and state is present at ${input.statePath}; answering binary ${binary}`,
+    };
+  }
+  return {
+    level: 'warn',
+    detail: `bandit re-ranking is on but state is absent at ${input.statePath}; answering binary ${binary}`,
+  };
+}

package/src/feature-tier.ts

@@ -1,7 +1,20 @@
 import type { FeatureTier } from './guard-volume.js';
 
+/**
+ * Начало строки, на котором тир ещё считается ОБЪЯВЛЕННЫМ, а не упомянутым в прозе: необязательный
+ * маркер списка (`-`, `*`, `+`, `1.`), необязательный заголовок и необязательное выделение.
+ *
+ * Маркер списка добавлен 2026-09-21 по измерению: `00_complexity_assessment.md` фичи
+ * `amendment-seams` несёт строку `- **Tier: S** — …`, и парсер её НЕ видел. Следствие было не
+ * косметическим: `dz contract-check --slug amendment-seams` отвечал NOT-ESTABLISHED с диагнозом
+ * «required ADR directory cannot be resolved», хотя в самом приборе есть верная ветка «тиру S
+ * каталог ADR не требуется» — она просто никогда не исполнялась, потому что тир читался как
+ * неизвестный. То есть вердикт называл не ту причину и отправлял чинить не то (бэклог 5d436aa6).
+ */
+const TIER_LINE_START = /^\s*(?:[-*+]\s+|\d+[.)]\s+)?(?:##+\s*)?(?:\*\*)?(?:Tier|Тир)(?=$|[\s:*])/iu;
+
 function tiersAfterMarkers(line: string): FeatureTier[] {
-  if (!/^\s*(?:##\s*)?(?:\*\*)?(?:Tier|Тир)(?=$|[\s:*])/iu.test(line)) return [];
+  if (!TIER_LINE_START.test(line)) return [];
   const tiers: FeatureTier[] = [];
   for (const marker of line.matchAll(/Tier|Тир/giu)) {
     const markerIndex = marker.index ?? 0;

package/src/guard.ts

@@ -1338,6 +1338,18 @@ export interface GuardAuditRecord {
   readonly observations?: readonly GuardObservation[];
   /** set when the operator overrode a block with `--force <reason>` — the override is logged, never silent. */
   readonly override?: { readonly forced: true; readonly reason: string };
+  /**
+   * Ids of every rule this run EVALUATED — `checked` plus `notEstablished`, because both mean the
+   * rule was active for the op and got its turn.
+   *
+   * Why the log needs it (backlog 1bee49dd): a guard rule's zero-firing state is its HEALTHY state,
+   * so `violations[]` cannot tell a working safety net from a dead rule. MEASURED 2026-09-21 on
+   * `.dz/guard-audit.jsonl`: 1854 rows, 26 default rules, 6 of which never appear in any violations
+   * array — and 4 of those 6 are not allowlisted, so the moment the report's history floor is met
+   * they would be named dead for doing their job. The evaluation set was already computed in
+   * `GuardResult`; only the record dropped it.
+   */
+  readonly evaluated?: readonly string[];
 }
 
 /** Build the audit record for a guard evaluation (+ an optional forced-override reason). Pure. */
@@ -1350,9 +1362,21 @@ export function auditRecord(result: GuardResult, ts: string, override?: { reason
     ...(Array.isArray(result.notes) && result.notes.length > 0 ? { notes: result.notes } : {}),
     ...(Array.isArray(result.observations) && result.observations.length > 0 ? { observations: result.observations } : {}),
     ...(override && typeof override.reason === 'string' ? { override: { forced: true, reason: override.reason } } : {}),
+    ...(evaluatedRuleIds(result).length > 0 ? { evaluated: evaluatedRuleIds(result) } : {}),
   };
 }
 
+/**
+ * Every rule that got its turn this run, sorted and de-duplicated. A rule with no input still RAN —
+ * calling that "not evaluated" would reintroduce the very conflation this field exists to remove.
+ */
+export function evaluatedRuleIds(result: GuardResult): string[] {
+  const ids = new Set<string>();
+  for (const id of Array.isArray(result.checked) ? result.checked : []) if (typeof id === 'string' && id !== '') ids.add(id);
+  for (const id of Array.isArray(result.notEstablished) ? result.notEstablished : []) if (typeof id === 'string' && id !== '') ids.add(id);
+  return [...ids].sort();
+}
+
 /** The exit-code contract: a block is non-zero unless forced; a warn/pass is zero. */
 export function guardExitCode(result: GuardResult, forced: boolean): number {
   return result.verdict === 'block' && !forced ? 1 : 0;

package/src/index.ts

@@ -78,6 +78,8 @@ export {
 } from './parity.js';
 export type { RuntimeCapability, FeatureForm, ParityFeature, ParityCell, ParityReportCell, ParityMatrixRow, CapabilityEvidence, UnbackedCapability, ProbedRuntimeVersions } from './parity.js';
 export * from './operations.js';
+export { checkInstrumentFreshness, checkRankingState } from './doctor-instrument.js';
+export type { InstrumentFreshness, InstrumentCheckInput, InstrumentCheckResult, RankingStateCheckInput, RankingStateCheckResult } from './doctor-instrument.js';
 // workflows.ts: the ADR-005 templates are RETIRED (feature loop-designer, AM-6) — the module is a
 // deprecation shim (empty WORKFLOW_NAMES). BREAKING for external harness-core consumers of
 // WorkflowTemplate/WORKFLOWS/getWorkflow — deliberately channeled through the 0.x MINOR bump and
@@ -137,7 +139,7 @@ export type { RepoBoundaryIo } from './repo-boundary.js';
 export type { LedgerBackfillPlan, LedgerBackfillRow, RunCostFacts } from './ledger-backfill.js';
 export type { SweepResult, DriftedSkill, SyncResult, SyncCanonicalOptions } from './skill-drift.js';
 export { benchmarkSkill, benchmarkSkills, compareSkills } from './benchmark.js';
-export { buildRegistry, searchRegistry, filterByCategory, skillPackBaseDirs, discoverSkillPackDirs, discoverSkillCarryingDirs, discoverVerifiablePackDirs } from './registry.js';
+export { buildRegistry, buildShowcaseRegistry, searchRegistry, filterByCategory, skillPackBaseDirs, discoverSkillPackDirs, discoverSkillCarryingDirs, discoverVerifiablePackDirs, packScope, verifiedScopeNote } from './registry.js';
 export { tokenize, stemToken, stems } from './stem.js';
 // Package skill-layout resolution (feature dz-install-npx-init) — the ONE seam that knows where an
 // npm package keeps its skills (flat / templates/.claude/skills / skills). `cmdInstall` calls it;
@@ -782,6 +784,7 @@ export {
   planReleaseGates,
   classifyGateExecutions,
   buildFailureIssue,
+  shouldRetryGhWithoutToken,
   buildReleaseNotes,
   releaseTagName,
   firstOutputLine,
@@ -881,7 +884,7 @@ export type {
   McpSeverity,
   McpCapability,
 } from './mcp-scan.js';
-export type { RegistryEntry, Registry } from './registry.js';
+export type { RegistryEntry, Registry, ShowcaseRegistry, ShowcaseSkill } from './registry.js';
 export type { BenchmarkCheck, BenchmarkScore, BenchmarkReport, CompareResult } from './benchmark.js';
 export {
   specToOpts,

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;