@dzhechkov/harness-core 0.8.38 → 0.8.40

package/src/agentdb-index.ts

@@ -1168,9 +1168,9 @@ export async function importVectorsToAgentdb(
 }
 
 /**
- * lesson-quarantine: clear the `qStatus` marker from mirrored rows after a promotion — the hook
- * daemon reads ONLY this mirror's metadata, so a promoted lesson must stop being excluded there
- * too. Best-effort, same custody model as {@link bumpAgentdbUses} (missing db/deps ⇒ no-op).
+ * lesson-quarantine: mark mirrored rows as promoted after a promotion — the hook daemon reads ONLY
+ * this mirror's metadata, so a promoted lesson must stop being excluded there while retaining its
+ * quarantine history. Best-effort, same custody model as {@link bumpAgentdbUses} (missing db/deps ⇒ no-op).
  */
 export function clearAgentdbQuarantine(
   projectRoot: string,
@@ -1194,12 +1194,12 @@ export function clearAgentdbQuarantine(
       db.pragma('busy_timeout = 5000');
       db.exec(REASONING_BANK_SCHEMA);
       const stmt = db.prepare(
-        "UPDATE reasoning_patterns SET metadata = json_remove(metadata, '$.qStatus', '$.quarantinedAt') WHERE json_extract(metadata, '$.dzId') = ? AND json_extract(metadata, '$.qStatus') = 'quarantined'",
+        "UPDATE reasoning_patterns SET metadata = json_set(metadata, '$.qStatus', 'promoted', '$.promotedAt', ?) WHERE json_extract(metadata, '$.dzId') = ? AND json_extract(metadata, '$.qStatus') = 'quarantined'",
       );
       const tx = db.transaction(() => {
         let cleared = 0;
         for (const dzId of dzIds) {
-          const r = stmt.run(dzId);
+          const r = stmt.run(new Date().toISOString(), dzId);
           cleared += Number((r as unknown as { changes?: number }).changes ?? 0);
         }
         return cleared;

package/src/amendment-trace.ts

@@ -138,7 +138,10 @@ export function extractTestTitles(body: string): string[] {
 }
 
 export function normalizeTestId(s: string): string {
-  return s.toLowerCase().replace(/[^a-z0-9]+/g, '');
+  // Unicode letter/number classes: the old `[^a-z0-9]` erased Cyrillic outright, so a Russian test title
+  // normalised to '' and tripped the floor as the author's fault (MEASURED 2026-09-04, backlog 191853a2).
+  // Re-run over all 519 features on 2026-09-20: zero verdicts changed — this only adds matches.
+  return s.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '');
 }
 
 /**

package/src/backlog.ts

@@ -266,7 +266,7 @@ export function readBacklogConfig(projectRoot: string): BacklogConfig {
 }
 
 /* ================================================================== */
-/*  STORE (AM-1) — .dz/backlog/ideas.jsonl (append-only JSONL, ADR-005) */
+/*  STORE (AM-1) — .dz/backlog/ideas.jsonl (JSONL rewritten WHOLE per write, ADR-005 + amendment 2026-09-20) */
 /* ================================================================== */
 
 export function backlogDir(projectRoot: string): string {
@@ -335,7 +335,8 @@ function normaliseIdea(raw: Record<string, unknown>): IdeaRecord | undefined {
   return rec;
 }
 
-/** Read the append-only store. A corrupt line is SKIPPED (never fatal) — the whole store never throws. */
+/** Read the store (one current line per id — `writeIdeas` rewrites it whole and never appends). A corrupt
+ *  line is SKIPPED (never fatal) — the whole store never throws. */
 export function readIdeas(projectRoot: string): IdeaRecord[] {
   const path = ideasPath(projectRoot);
   if (!existsSync(path)) return [];

package/src/brain.ts

@@ -21,6 +21,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdir
 import { pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
 import { spawn } from 'node:child_process';
+import { openSqliteReadOnly } from '@dzhechkov/memory';
 import { putBookKnowledge, queryBookKnowledge, bookKbPath, type BookKU, type BookKUHit } from './book-kb.js';
 import { indexPatternsToAgentdb, searchAgentdbPatterns, reindexAgentdbRows, type AgentdbRow } from './agentdb-index.js';
 import type { SnapshotRotationReport } from './agentdb-snapshot-rotation.js';
@@ -193,7 +194,8 @@ export function readBookKus(opts: {
     return { kus: [], error: 'better-sqlite3 not installed (run: dz setup --memory agentdb)' };
   }
   try {
-    const db = new Database(opts.storePath, { readonly: true });
+    const handle = openSqliteReadOnly(opts.storePath, { Database });
+    const db = handle.db as NativeDb;
     try {
       const cols = 'book, ku_id, corpus_version, type, name, problem, content, chapter, pages, metadata';
       const rows = (opts.source !== undefined
@@ -201,7 +203,11 @@ export function readBookKus(opts: {
         : db.prepare(`SELECT ${cols} FROM book_knowledge`).all()) as ProjRow[];
       return { kus: rows.map(rowToKu) };
     } finally {
-      db.close();
+      try {
+        db.close();
+      } finally {
+        handle.cleanup();
+      }
     }
   } catch (err) {
     return { kus: [], error: `read book KB failed: ${err instanceof Error ? err.message : String(err)}` };

package/src/bto-optimize.ts

@@ -20,6 +20,8 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 
+import { maskMarkdown } from './markdown-masker.js';
+
 export type BtoDimension = 'METHODOLOGY' | 'DEPTH' | 'CORRECTNESS' | 'USABILITY' | 'ROBUSTNESS';
 export const BTO_DIMENSIONS: readonly BtoDimension[] = Object.freeze(['METHODOLOGY', 'DEPTH', 'CORRECTNESS', 'USABILITY', 'ROBUSTNESS']);
 export type DimScores = Record<BtoDimension, number>;
@@ -203,22 +205,22 @@ const bodyAfterFrontmatter = (t: string): string => {
 
 /**
  * ALL structural markers on the BODY, not just space-delimited ATX (QE: `##\tNEW`, bare `##`, and setext
- * `Title\n===` / `Title\n---` evaded the old regex). Fenced code blocks (``` / ~~~) are SKIPPED so a `===`/`---`
- * line INSIDE code is not misread as a heading (QE false-positive). Collect ATX (`#`..`######` + any/no ws)
- * AND setext underlines (a non-empty line immediately followed by `=+`/`-+`).
+ * `Title\n===` / `Title\n---` evaded the old regex). The canonical masker skips fenced code blocks before
+ * collecting ATX (`#`..`######` + any/no ws) and setext underlines (a non-empty line immediately followed
+ * by `=+`/`-+`). Its `unclosed: 'restore'` policy is load-bearing: measured over 7,121 headed Markdown
+ * documents, the old parity toggle missed a deletion in 39 documents, masking with `hide` missed 22, and
+ * masking with `restore` missed 0.
  */
 const headings = (t: string): string[] => {
-  const lines = bodyAfterFrontmatter(t).split('\n');
+  const body = bodyAfterFrontmatter(t);
+  const lines = maskMarkdown(body, { unclosed: 'restore' }).split('\n');
   const out: string[] = [];
-  let inFence = false;
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]!;
-    if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; continue; }
-    if (inFence) continue;
     const atx = /^(#{1,6})(?:\s.*)?$/.exec(line.replace(/\s+$/, ''));
     if (atx) { out.push('ATX:' + line.trim()); continue; }
     const next = lines[i + 1];
-    if (line.trim() !== '' && !/^\s*(```|~~~)/.test(next ?? '') && next !== undefined && /^(=+|-+)\s*$/.test(next)) {
+    if (line.trim() !== '' && next !== undefined && /^(=+|-+)\s*$/.test(next)) {
       out.push('SETEXT:' + line.trim() + '|' + next.trim());
     }
   }

package/src/claim-check.ts

@@ -122,6 +122,8 @@ function paragraphAround(lines: readonly string[], i: number): string {
 /** Tags that make a claim honest (case-insensitive). */
 // `estimated` agrees with the `estimated: true` honest-uncertainty marker `dz usage` already
 // emits — the two honesty systems must not contradict each other.
+import { maskMarkdown } from './markdown-masker.js';
+
 const HONEST_TAGS = ['measured', 'claimed', 'synthetic', 'unvalidated', 'baseline', 'estimated'];
 
 /**
@@ -136,17 +138,27 @@ const HONEST_TAGS = ['measured', 'claimed', 'synthetic', 'unvalidated', 'baselin
  */
 export function isFenced(text: string, line: number): boolean {
   if (typeof text !== 'string' || typeof line !== 'number' || !isFinite(line) || line < 1) return false;
-  const lines = text.split(/\r?\n/);
-  const upTo = Math.min(line - 1, lines.length);
-  let open: '`' | '~' | null = null;
-  for (let i = 0; i < upTo; i++) {
-    const m = FENCE_RE.exec(lines[i] || '');
-    if (!m) continue;
-    const marker = m[1]![0] as '`' | '~';
-    if (open === null) open = marker;
-    else if (open === marker) open = null;
-  }
-  return open !== null;
+  // DELEGATED to the canonical masker. The local walk this replaces already tracked the marker
+  // CHARACTER — the naive-toggle bug the comment above describes was genuinely fixed — but it still
+  // broke two further CommonMark rules, and both were MEASURED 2026-09-20 to answer `false` for a
+  // line that IS inside a block: a closing fence may carry NO info string, so a second info-string
+  // line closed the block; and a closing fence may not be SHORTER than the opening one, so a
+  // three-backtick line closed a four-backtick block. Both make the engine scan a QUOTED example as
+  // a real claim, and make the hook's deny path stop exempting it.
+  //
+  // `unclosed: 'hide'` keeps the local walk's policy: an unclosed opener leaves every later line
+  // inside the block. One deliberate difference: the OPENING delimiter line now answers `true` (the
+  // local walk answered `false` for it and `true` for the closing one) — an info string is not
+  // prose, and the two delimiters answering differently was an artifact, not a decision.
+  let masked = false;
+  try {
+    const target = line - 1;
+    maskMarkdown(text.replace(/\r\n/g, '\n'), {
+      unclosed: 'hide',
+      onMasked: (i?: number) => { if (i === target) masked = true; },
+    });
+  } catch { return false; }
+  return masked;
 }
 
 const FENCE_RE = /^\s*(`{3,}|~{3,})/;
@@ -189,9 +201,33 @@ const MAP_METRIC_RE = new RegExp(
  * A shell reproducer is STRUCTURAL, never a word. `(MEASURED — reproducer)` is self-certifying and
  * must not pass; a backticked span whose first token is a command this repo actually measures with is
  * evidence. The allowlist boundary is exactly that: an unknown binary is a claim ABOUT evidence.
+ *
+ * `python3` joined the list for backlog 0b53470a, on the list's OWN criterion rather than by
+ * widening it: `packages/@dzhechkov/health-advisor/test/goap-python-suite.test.js` makes
+ * `python3 -m unittest discover` a GATE, so it is a command this repo measures with. Before the
+ * addition a Python measurer could not cite itself — MEASURED by twins, one line differing only in
+ * the backticked binary: `python3 …` → 1 finding "Tagged MEASURED but cites no reproducer",
+ * `pytest …` → 0, `git show …` → 0. Bare `python` was deliberately NOT added (cross-family review
+ * r1, MEDIUM): the gate this repo runs is `python3`, and the only measured usage in the tree is
+ * `python3 -m unittest` — an entry nothing measures with would be exactly the "claim ABOUT
+ * evidence" this list refuses. The list stays CLOSED: a measurer in any other language meets the
+ * same wall and needs the same deliberate entry. That is the price of the boundary, not a defect.
+ *
+ * THE BOUNDARY IS `(?![\w-])`, NOT `\b`, and that turned out to matter far beyond python
+ * (cross-family review r1, HIGH). `\b` treats a hyphen as a word boundary, so every backticked
+ * FILE NAME that begins with a listed command counted as a reproducer. MEASURED 2026-09-19:
+ * `pnpm-lock.yaml`, `dz-harness-hub`, `git-workflow` and `npm-shrinkwrap.json` all passed as
+ * evidence for a MEASURED claim, while `node_modules` was correctly refused — only because `_` is
+ * a word character and `-` is not. The repository holds hundreds of such tokens, so the check has
+ * been accepting file names as measurements for as long as the list has existed.
+ *
+ * WHAT THIS CHECK DOES NOT DO, said plainly because the previous wording implied more: it verifies
+ * the SHAPE of a citation, never that a measurement happened. `git --version` in backticks is
+ * accepted by construction — validating arguments per binary is a different mechanism with a
+ * different cost, and pretending otherwise would be the very laundering this file exists to stop.
  */
 const SHELL_REPRO_RE =
-  /`\s*\$?\s*(?:ps|stat|lsof|time|git|npm|npx|node|pnpm|yarn|dz|curl|wc|grep|find|cargo|make|docker|kubectl|awk|sed|du|df|vitest|pytest)\b[^`]*`/i;
+  /`\s*\$?\s*(?:ps|stat|lsof|time|git|npm|npx|node|pnpm|yarn|dz|curl|wc|grep|find|cargo|make|docker|kubectl|awk|sed|du|df|vitest|pytest|python3)(?![\w-])[^`]*`/i;
 
 /** Reproducer references that count as evidence backing a MEASURED claim. */
 const REPRODUCER_HINTS = [

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}`,
+  };
+}