@dzhechkov/harness-core 0.8.39 → 0.8.41

package/src/reqe.ts

@@ -9,8 +9,8 @@
  * DEBT with a lifecycle:
  *
  *   emit   — the workflow records features/<slug>/.fa-state/reqe-due.json when Step-8 actually ran
- *            same-family under the override (not on every switch — a switch before Step 8 that
- *            still got cross-family QE creates no debt);
+ *            same-family after a usage switch, failed probe, fallback or explicit QE pin;
+ *            a review that stayed cross-family creates no debt;
  *   list   — `dz reqe` scans the debts; `dz usage` surfaces the count so the moment limits free up
  *            is the moment the debt is visible;
  *   brief  — `dz reqe --slug <s>` prints a ready cross-family review brief (the OTHER family than
@@ -18,19 +18,37 @@
  *   settle — `dz reqe --slug <s> --done --report <file>` clears the debt FAIL-CLOSED: only against
  *            an existing, non-trivial report that names a grade; the settlement is appended to
  *            08_qe_report.md so the artifact trail closes.
+ * The two-part verdict reports new and prior findings separately; blocked new findings signal CLI exit 3.
  *
  * HONEST SCOPE: nothing here re-runs QE automatically (no background spend — the human decides);
- * the same-family CLAUDE belt fallback (codex unavailable) is out of scope by design — it is
- * already logged loudly at run time and is not a limit-pressure artifact; runs from before this
- * feature carry no marker and are UNDETERMINABLE, not debt-free.
+ * routing-off runs are excluded by configuration. Old checkpoints without bridge facts or a usage
+ * marker are UNDETERMINABLE and explicitly degraded.
  */
 
+import { buildReqeVerdict, type ReqeVerdict } from './reqe-verdict.js';
+
 export const REQE_SCHEMA = 'reqe-due-1';
 
 export const REQE_SCOPE =
-  'scope: debt is emitted only when Step-8 QE actually ran on the coder’s own family under the ' +
-  'usage override; settling requires a graded cross-family report (fail-closed); nothing re-runs QE ' +
-  'automatically.';
+  'scope: same-family Step-8 QE records cause=usage-switched, probe-failed, same-family-fallback ' +
+  'or same-family-pinned; routing OFF is excluded by configuration; settling requires a graded ' +
+  'cross-family report (fail-closed); nothing re-runs QE automatically.';
+
+export type ReqeCause = 'usage-switched' | 'probe-failed' | 'same-family-fallback' | 'same-family-pinned';
+export type ReqeRungState = 'pending' | 'dispatched' | 'probe-failed' | 'refused-before-dispatch';
+export interface ReqeBridgeFacts {
+  happened: boolean | null;
+  rungState: ReqeRungState | null;
+  rungReason: string | null;
+  decline: string | null;
+}
+export interface ReqeEmitInput {
+  coderUsed: string | null | undefined;
+  qeReviewerUsed: string | null | undefined;
+  qeModelLabel: string | null | undefined;
+  routingRequested: boolean | null | undefined;
+  bridge?: ReqeBridgeFacts | null;
+}
 
 export type ModelFamily = 'claude' | 'openai';
 
@@ -46,35 +64,57 @@ export function modelFamily(spec: string | null | undefined): ModelFamily {
 export interface ReqeEmitDecision {
   emit: boolean;
   reason: string;
+  cause: ReqeCause | null;
+  degraded: boolean;
 }
 
-/** Emit iff the QE stage label carries the workflow's ' (usage-switched)' marker AND the reviewer
- * family equals the coder family. Marker-only (cross-family survived the switch) or same-family
- * WITHOUT the marker (the codex-unavailable Claude belt — degraded loudly at run time, not a
- * limit-pressure artifact) both create NO debt. */
-export function shouldEmitReqeDebt(input: {
-  coderUsed: string | null | undefined;
-  qeReviewerUsed: string | null | undefined;
-  qeModelLabel: string | null | undefined;
-}): ReqeEmitDecision {
-  const switched = /\(usage-switched\)/.test(String(input.qeModelLabel ?? ''));
+/** Families are authoritative; routing OFF is an explicit exclusion. For same-family reviews,
+ * classify usage overrides before probe failures, fallbacks and explicit pins. Missing checkpoint
+ * facts and unknown rung states stay visibly degraded rather than inventing a cause. */
+export function shouldEmitReqeDebt(input: ReqeEmitInput): ReqeEmitDecision {
   const coderFam = modelFamily(input.coderUsed);
   const qeFam = modelFamily(input.qeReviewerUsed);
-  if (switched && coderFam === qeFam) {
+  if (coderFam !== qeFam) {
+    return { emit: false, cause: null, degraded: false, reason: 'cross-family QE ran' };
+  }
+  if (input.routingRequested === false) {
+    return { emit: false, cause: null, degraded: false,
+      reason: 'same-family by configuration (cross-family never requested)' };
+  }
+  if (/\(usage-switched\)/.test(String(input.qeModelLabel ?? ''))) {
     return {
-      emit: true,
+      emit: true, cause: 'usage-switched', degraded: false,
       reason:
         'usage-switched self-review: Step-8 QE ran on the coder’s own family (' + coderFam +
         ') under the limit override — the cross-model guard was suspended (FR-2.9)',
     };
   }
-  if (switched) return { emit: false, reason: 'usage-switched but QE stayed cross-family (' + qeFam + ' vs coder ' + coderFam + ')' };
-  if (coderFam === qeFam) return { emit: false, reason: 'same-family without the usage override (belt degrade — logged loudly at run time; out of re-QE-debt scope)' };
-  return { emit: false, reason: 'cross-family QE ran' };
+  if (input.bridge?.rungState === 'probe-failed') {
+    return { emit: true, cause: 'probe-failed', degraded: false,
+      reason: 'codex probe found no usable id; review ran on the coder’s own family (' + coderFam + ')' };
+  }
+  if (input.bridge?.rungState === 'dispatched' || input.bridge?.rungState === 'refused-before-dispatch' ||
+      input.qeReviewerUsed === 'codex-fallback') {
+    return { emit: true, cause: 'same-family-fallback', degraded: false,
+      reason: 'same-family fallback: ' + (input.bridge?.decline ?? input.bridge?.rungReason ?? 'cross-family reviewer unavailable') +
+        '; review ran on the coder’s own family (' + coderFam + ')' };
+  }
+  if (input.bridge == null) {
+    return { emit: false, cause: null, degraded: true,
+      reason: "cause undeterminable (pre-change checkpoint) — re-run with resume:'never' to classify" };
+  }
+  if (input.routingRequested === true && input.bridge.rungState === 'pending') {
+    return { emit: true, cause: 'same-family-pinned', degraded: false,
+      reason: 'same-family by explicit qe pin (args.models.qe) while cross-family routing was requested' };
+  }
+  return { emit: false, cause: null, degraded: true,
+    reason: 'cause undeterminable (unknown rung state or routing request)' };
 }
 
 export interface ReqeDebt {
   schema: typeof REQE_SCHEMA;
+  cause: ReqeCause;
+  bridge?: ReqeBridgeFacts | null;
   slug: string;
   coderFamily: ModelFamily;
   qeFamily: ModelFamily;
@@ -97,15 +137,21 @@ export function buildReqeDebt(input: {
   qeGrade: string | null | undefined;
   reason: string;
   emittedAt?: string | null;
+  cause: ReqeCause;
+  bridge?: ReqeBridgeFacts | null;
+  runStamp?: string | null;
 }): ReqeDebt {
   return {
     schema: REQE_SCHEMA,
+    cause: input.cause,
+    ...(input.bridge === undefined ? {} : { bridge: input.bridge }),
     slug: input.slug,
     coderFamily: modelFamily(input.coderUsed),
     qeFamily: modelFamily(input.qeReviewerUsed),
     qeGrade: input.qeGrade == null || String(input.qeGrade).trim() === '' ? null : String(input.qeGrade).trim(),
     reason: input.reason,
     emittedAt: input.emittedAt ?? null,
+    runStamp: input.runStamp ?? null,
   };
 }
 
@@ -125,16 +171,21 @@ export function parseReqeDebt(text: string): ReqeDebt | null {
   if (d.coderFamily !== 'claude' && d.coderFamily !== 'openai') return null;
   if (d.qeFamily !== 'claude' && d.qeFamily !== 'openai') return null;
   if (typeof d.reason !== 'string' || d.reason.trim() === '') return null;
-  return {
-    schema: REQE_SCHEMA,
+  if (d.cause !== undefined && d.cause !== 'usage-switched' && d.cause !== 'probe-failed' &&
+      d.cause !== 'same-family-fallback' && d.cause !== 'same-family-pinned') return null;
+  return buildReqeDebt({
     slug: d.slug,
-    coderFamily: d.coderFamily,
-    qeFamily: d.qeFamily,
-    qeGrade: typeof d.qeGrade === 'string' && d.qeGrade.trim() !== '' ? d.qeGrade.trim() : null,
+    coderUsed: d.coderFamily,
+    qeReviewerUsed: d.qeFamily,
+    qeGrade: typeof d.qeGrade === 'string' ? d.qeGrade : null,
     reason: d.reason,
+    cause: d.cause ?? 'usage-switched',
+    ...(d.bridge === undefined ? {} : {
+      bridge: d.bridge && typeof d.bridge === 'object' && !Array.isArray(d.bridge) ? d.bridge : null,
+    }),
     emittedAt: typeof d.emittedAt === 'string' && d.emittedAt.trim() !== '' ? d.emittedAt : null,
     runStamp: typeof d.runStamp === 'string' && d.runStamp.trim() !== '' ? d.runStamp : null,
-  };
+  });
 }
 
 export interface ReqeBrief {
@@ -155,11 +206,12 @@ export function buildReqeBrief(debt: ReqeDebt, artifactsDir: string): ReqeBrief
     artifactsDir + '/03_adr/',
   ];
   const instructions = [
-    'Independent re-QE for "' + debt.slug + '": the recorded Step-8 review ran on the coder’s own family (' + debt.coderFamily + ') under the usage override' + (debt.qeGrade ? ' and graded ' + debt.qeGrade : '') + '.',
+    'Independent re-QE for "' + debt.slug + '": the recorded Step-8 review ran on the coder’s own family (' + debt.coderFamily + '); cause=' + debt.cause + (debt.qeGrade ? ' and graded ' + debt.qeGrade : '') + '.',
     'Review with the ' + reviewFamily.toUpperCase() + ' family (the OTHER family than the coder — the suspended guard, restored).',
     'Read: ' + files.join(' , ') + ' plus every file the change manifest lists.',
     'Adversarially verify: correctness, edge cases, the ADR-named load-bearing property HAS a test, and whether the same-family review missed anything.',
     'Output: GRADE A-F + numbered findings with file:line and severity; write the report to ' + artifactsDir + '/08b_reqe_report.md.',
+    'Also list every finding of the same-family 08_qe_report.md by number under a "## Prior findings" heading, one line each: <n>: closed|open — <reason>.',
     'Then settle the debt: dz reqe --slug ' + debt.slug + ' --done --report ' + artifactsDir + '/08b_reqe_report.md',
   ];
   const codexCmdTemplate = reviewFamily === 'openai'
@@ -178,6 +230,7 @@ export interface ReqeSettlement {
   error: string | null;
   grade: string | null;
   epilogue: string | null;
+  verdict: ReqeVerdict | null;
 }
 
 /** Extract the verdict grade from a report, or null. LINE-ANCHORED and range-proof (Codex QE #7):
@@ -212,12 +265,18 @@ export function extractReportGrade(text: string): string | null {
 export function settleReqeDebt(debt: ReqeDebt, reportText: string, reportPath: string): ReqeSettlement {
   const text = String(reportText ?? '');
   if (text.trim().length < 200) {
-    return { ok: false, error: 'report too small to be a review (< 200 chars of substance) — refusing to settle', grade: null, epilogue: null };
+    return { ok: false, error: 'report too small to be a review (< 200 chars of substance) — refusing to settle', grade: null, epilogue: null, verdict: null };
   }
   const grade = extractReportGrade(text);
   if (grade === null) {
-    return { ok: false, error: 'report names no unambiguous line-anchored GRADE (A-F) — text without exactly one verdict grade is not a verdict; refusing to settle', grade: null, epilogue: null };
+    return { ok: false, error: 'report names no unambiguous line-anchored GRADE (A-F) — text without exactly one verdict grade is not a verdict; refusing to settle', grade: null, epilogue: null, verdict: null };
   }
+  const verdict = buildReqeVerdict(text);
+  const { counts, findings, prior } = verdict;
+  const priorSummary = prior.kind === 'closed' ? `closed (${prior.closed}/${prior.total})`
+    : prior.kind === 'open' ? `open(${prior.open.length}) of ${prior.total}` : 'unassessed';
+  const mismatch = findings.kind === 'accepted' && findings.declared !== null && findings.declared !== findings.rows
+    ? ` (declared ${findings.declared}, parsed ${findings.rows})` : '';
   const reviewFamily: ModelFamily = debt.coderFamily === 'openai' ? 'claude' : 'openai';
   const epilogue = [
     '',
@@ -230,24 +289,41 @@ export function settleReqeDebt(debt: ReqeDebt, reportText: string, reportPath: s
     '',
     '- report: `' + reportPath + '`',
     '- re-QE grade: **' + grade + '**' + (debt.qeGrade ? ' (same-family grade on record: ' + debt.qeGrade + ')' : ''),
+    `- new findings: ${verdict.new} — BLOCKER ${counts.blocker}, HIGH ${counts.high}, MEDIUM ${counts.medium}, LOW ${counts.low}, unknown ${counts.unknown} (rows ${verdict.rows})${mismatch}`,
+    `- prior findings: ${priorSummary}`,
+    ...(findings.kind === 'accepted' ? [] : [
+      `- findings: unclassified (${findings.kind === 'absent' ? 'absent' : `rejected: ${findings.reason}`})`,
+    ]),
+    ...verdict.blocking.map((row) => `- ${row.severity} — ${row.title}${row.where === null ? '' : ` (${row.where})`}`),
+    '- severities and prior-finding status as declared by the reviewer; dz reqe counts them, it does not judge them.',
     '- settled via `dz reqe --done` (fail-closed: an existing graded report is required).',
     '',
   ].join('\n');
-  return { ok: true, error: null, grade, epilogue };
+  return { ok: true, error: null, grade, epilogue, verdict };
 }
 
 /** Render the debt list for `dz reqe` / the `dz usage` surfacing line. */
 export function renderReqeList(debts: readonly ReqeDebt[], malformed: number): string[] {
   const lines: string[] = [];
   if (debts.length === 0 && malformed === 0) {
-    lines.push('dz reqe: no re-QE debts — every recorded run kept cross-model QE (or none used the usage override).');
+    lines.push('dz reqe: no re-QE debts — no unsettled machine debts recorded.');
   } else {
     lines.push('dz reqe — ' + debts.length + ' unsettled re-QE debt(s):');
     for (const d of debts) {
-      lines.push('  ' + d.slug + '  coder=' + d.coderFamily + ' qe=' + d.qeFamily + (d.qeGrade ? ' grade=' + d.qeGrade : '') + (d.emittedAt ? '  ' + d.emittedAt : '') + '  → dz reqe --slug ' + d.slug);
+      lines.push('  ' + d.slug + '  coder=' + d.coderFamily + ' qe=' + d.qeFamily + (d.qeGrade ? ' grade=' + d.qeGrade : '') + (d.emittedAt ? '  ' + d.emittedAt : '') + ' cause=' + d.cause + '  → dz reqe --slug ' + d.slug);
     }
   }
   if (malformed > 0) lines.push('  ' + malformed + ' malformed debt file(s) skipped (named, never silent).');
   lines.push(REQE_SCOPE);
   return lines;
 }
+
+
+/** Stable keys, including zero counts, for the dz usage JSON output. */
+export function countReqeByCause(debts: readonly ReqeDebt[]): Record<ReqeCause, number> {
+  const counts: Record<ReqeCause, number> = {
+    'usage-switched': 0, 'probe-failed': 0, 'same-family-fallback': 0, 'same-family-pinned': 0,
+  };
+  for (const debt of debts) counts[debt.cause] += 1;
+  return counts;
+}

package/src/round-exec.ts

@@ -37,14 +37,25 @@ export function classifyRoundExecOutcome(input: {
   readonly exitCode: number | null;
   readonly timedOut: boolean;
   readonly bytes: number;
+  /** How the run ENDED: the limit/refusal signatures are end-state facts, so they read the tail. */
   readonly tail: string;
+  /**
+   * The WHOLE log, when the caller has it. The turn marker is not an end-state fact — it is the last
+   * `\ncodex\n` ANYWHERE in the log — and a fixed tail window cannot hold it: MEASURED 2026-09-20 on
+   * three real rounds, Codex's final answer ran 12–20 KB (it quotes runner output), so the marker sat
+   * at ~95% of the file and fell outside the caller's 4 KB tail. All three runs had landed their files
+   * and were green, and all three were recorded `failed`. Defaults to `tail` for callers that only
+   * have the window.
+   */
+  readonly fullText?: string;
 }): RoundExecOutcome {
   if (input.timedOut) return 'timeout';
   if (/rate limit|usage limit|limit reached/i.test(input.tail)) return 'session-limit';
   if (/HTTP 400|not supported when using Codex/i.test(input.tail)) return 'model-refused';
   if (input.exitCode === 0 && input.bytes > 0) {
-    const marker = input.tail.lastIndexOf('\ncodex\n');
-    const finalLine = marker < 0 ? '' : input.tail.slice(marker + '\ncodex\n'.length).split(/\r?\n/, 1)[0]?.trim() ?? '';
+    const haystack = input.fullText ?? input.tail;
+    const marker = haystack.lastIndexOf('\ncodex\n');
+    const finalLine = marker < 0 ? '' : haystack.slice(marker + '\ncodex\n'.length).split(/\r?\n/, 1)[0]?.trim() ?? '';
     if (finalLine !== '') return 'done';
   }
   if (input.exitCode === 0 && input.bytes === 0) return 'empty';

package/src/round.ts

@@ -41,9 +41,28 @@ export interface RoundExecState {
 }
 
 /** Additive row shape accepted by the existing run-cost ledger readers. */
+/**
+ * The row this version WRITES. It is deliberately not the shape the FILE holds: the ledger is
+ * append-only, so rows written before a field existed do not carry it. Read a stored line as
+ * `unknown` and put it through {@link validateClosedRoundLedgerRow} or your own guard — typing a
+ * historical line with this interface and dereferencing a later field as a guaranteed string is the
+ * defect this note exists to prevent (named by cross-family review, Codex gpt-5.6-sol, 2026-09-21).
+ */
 export interface RoundLedgerRow {
   readonly slug: string;
   readonly stage: 'round';
+  /**
+   * This round's identity as a FIELD. It is also the first token of `note`, and that prefix is what
+   * the confirmation read greps for — but a key that lives inside prose can only be joined by
+   * parsing prose. MEASURED on the COMMITTED `.dz/feature-adr/run-cost-ledger.jsonl` at `488f596c`
+   * (backlog c60cc857, whose own numbers had gone stale): of 436 rows, 99 are `round`, and the
+   * round's own identity sat in a FIELD 0 times out of 99 while sitting inside `note` prose 99 times
+   * out of 99. Other id fields exist on those rows — 28 carry `taskId`, 76 carry `stateId` — but
+   * they identify the TASK and the STATE FILE, not the round's ledger identity; 22 carry none of
+   * `runId`/`taskId`/`stateId` (those three exactly — `runnerId`, the host, is on all 99).
+   * Reproducer and pinning commit: package README, section `roundId`.
+   */
+  readonly roundId: string;
   readonly tier: null;
   readonly coder: string | null;
   readonly reviewer: string | null;
@@ -59,6 +78,16 @@ export interface RoundLedgerRow {
   readonly reason: string | null;
   readonly round: number;
   readonly lessons: readonly string[];
+  /** Recall coverage for the "доведённая работа" metric: measured on 2026-09-21, 0 of 462
+   * ledger rows carried `recalled`, losing the shown-to-used link across 124 round rows.
+   * Preserve the lessons shown at open as exact IDs, deduplicated by Set and sorted; omit when empty. */
+  readonly recalled?: readonly string[];
+  /** Used lessons drawn from the shown set: `recalled` intersected with `lessons`, sorted and
+   * omitted when empty. Lessons obtained elsewhere do not count toward recall coverage. */
+  readonly recalledUsed?: readonly string[];
+  /** Shown lessons not used: `recalled` minus `lessons`, sorted and omitted when empty. Together
+   * with `recalledUsed`, preserves the denominator for the "доведённая работа" metric. */
+  readonly recalledUnused?: readonly string[];
   readonly noNewKnowledge: string | null;
   readonly note: string;
   readonly date: null;
@@ -549,9 +578,15 @@ export function closeRound(input: {
     ? (nonEmpty(input.shipTreeDirtyReason) ? input.shipTreeDirtyReason.trim() : 'not provided')
     : undefined;
 
+  const recalled = [...new Set(input.state.recalled)].sort();
+  const usedLessons = new Set(lessons);
+  const recalledUsed = recalled.filter((id) => usedLessons.has(id));
+  const recalledUnused = recalled.filter((id) => !usedLessons.has(id));
+
   const row: RoundLedgerRow = {
     slug: input.state.slug,
     stage: 'round',
+    roundId: marker,
     tier: null,
     coder: nonEmpty(input.coder) ? input.coder.trim() : null,
     reviewer,
@@ -564,6 +599,9 @@ export function closeRound(input: {
     reason: nonEmpty(input.reason) ? input.reason.trim() : null,
     round: input.state.round,
     lessons,
+    ...(recalled.length > 0 ? { recalled } : {}),
+    ...(recalledUsed.length > 0 ? { recalledUsed } : {}),
+    ...(recalledUnused.length > 0 ? { recalledUnused } : {}),
     noNewKnowledge: noNewKnowledge === '' ? null : noNewKnowledge,
     note: note === '' ? marker : `${marker} | ${note}`,
     date: null,

package/src/session-retro.ts

@@ -18,7 +18,7 @@ import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, cl
 import { join, basename, dirname } from 'node:path';
 import { homedir } from 'node:os';
 
-import { withNamedLockSync, NamedLockTimeoutError } from './named-lock.js';
+import { withProjectLockSync, NamedLockTimeoutError } from './named-lock.js';
 
 export interface SessionEvent {
   readonly kind: 'user' | 'assistant' | 'tool';
@@ -696,7 +696,7 @@ const writeJsonAtomic = (path: string, value: unknown): void => {
  * a partial trailing line is left for the next scan) → fold the debt → persist state + sentinel.
  * NEVER throws (it runs inside a Stop hook; a broken scan must never surface as a turn failure).
  *
- * The WHOLE read→fold→write runs under `withNamedLockSync` (cross-family QE P1-3): two overlapping
+ * The WHOLE read→fold→write runs under `withProjectLockSync` (cross-family QE P1-3): two overlapping
  * Stop scans that both read the same offset/sentinel and then rename/unlink independently lose one
  * side's update — atomic per-file renames do not prevent that, only mutual exclusion does. The
  * critical section is short and synchronous (bounded ≤8 MB read, no subprocess, 65 ms measured on
@@ -707,7 +707,7 @@ const writeJsonAtomic = (path: string, value: unknown): void => {
 export function runRetroTailScan(dzDir: string, transcriptPath: string | null, nowIso?: string): TailScanOutcome {
   if (transcriptPath === null || transcriptPath === '') return { status: 'no-transcript', scannedBytes: 0, offset: 0 };
   try {
-    return withNamedLockSync(
+    return withProjectLockSync(
       dirname(dzDir),
       RETRO_SCAN_LOCK_NAME,
       () => scanTailUnderLock(dzDir, transcriptPath, nowIso),

package/src/skill-drift.ts

@@ -42,6 +42,18 @@ export interface DriftedSkill {
   readonly locations: readonly string[];
 }
 
+export type CanonicalDefectKind = 'misplaced-enrichment-asset';
+
+/** A finding in the canonical source, reported without propagating or removing it. */
+export interface CanonicalDefect {
+  readonly skill: string;
+  readonly kind: CanonicalDefectKind;
+  /** Skill-dir-relative POSIX path. */
+  readonly path: string;
+  /** Absolute canonical skill directory. */
+  readonly canonical: string;
+}
+
 /** Options for {@link sweepSkillDrift}. */
 export interface SweepOptions {
   /**
@@ -69,6 +81,8 @@ export interface SweepResult {
   readonly duplicated: number;
   /** Skills that byte-differ AND are not allowlisted, sorted by `driftFiles` desc — the gate keys on this. */
   readonly drifted: readonly DriftedSkill[];
+  /** Canonical-side findings, independent of copy drift and its allowlist. */
+  readonly canonicalDefects: readonly CanonicalDefect[];
   /** Skills that byte-differ but are allowlisted (intentional) — surfaced for transparency, not gated. */
   readonly allowlisted: readonly DriftedSkill[];
 }
@@ -112,12 +126,22 @@ export interface SyncResult {
   readonly synced: number;
   /** # copies/files that differ (from canonical in resolved modes; between peers in canonical-free mode). */
   readonly drifted: number;
+  /** Nonempty in write mode means refusal: `synced: 0`, `wrote: []`. */
+  readonly canonicalDefects: readonly CanonicalDefect[];
   /** Abs paths of copies written (empty when `check:true` / peer / refuse — proves no writes). */
   readonly wrote: readonly string[];
 }
 
 const SKILL_MANIFEST = 'SKILL.md';
-const IGNORED_ENTRIES = new Set(['node_modules', '__pycache__', '.DS_Store', 'run-history.json']);
+// Runtime state, never skill CONTENT. `.agentic-qe/` earned its place by measurement on
+// 2026-09-21: merely INVOKING the decision-mockups skill made its AQE runtime create a SQLite
+// store inside the live `.claude/skills/decision-mockups/`, which the packaged copies do not
+// have — so `no-skill-drift` reported drift and BLOCKED `dz guard --op publish`. The directory
+// is gitignored repo-wide (`**/.agentic-qe/`) and untracked; the drift sweep simply did not read
+// .gitignore. Note the denylist stays narrow on purpose: a blanket "skip dot-entries" would
+// silence real drift in the nine packages whose skill content legitimately lives under
+// `templates/.claude/`.
+const IGNORED_ENTRIES = new Set(['node_modules', '__pycache__', '.DS_Store', 'run-history.json', '.agentic-qe']);
 
 /** md5 of a file's bytes (identical to both prototype scripts ⇒ identical drift verdicts). */
 function md5(path: string): string {
@@ -127,7 +151,13 @@ function md5(path: string): string {
 /** Recursive file list under `dir`; skips `node_modules` / `__pycache__` / `.DS_Store`. */
 function walk(dir: string): string[] {
   const out: string[] = [];
-  for (const entry of readdirSync(dir)) {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
     if (IGNORED_ENTRIES.has(entry)) continue;
     const p = join(dir, entry);
     let st;
@@ -181,11 +211,25 @@ function withoutEnrichmentNames(rels: readonly string[]): string[] {
   return rels.filter((r) => TARGET_ENRICHMENT_ASSETS[r.split(sep).join('/')] === undefined);
 }
 
-function comparePeers(copies: readonly string[]): { driftFiles: number; missingFiles: number; totalFiles: number } {
+/** Find misplaced target metadata in a canonical source, sorted by relative POSIX path. */
+export function findCanonicalDefects(canonicalDir: string, skill: string): CanonicalDefect[] {
+  const canonical = resolve(canonicalDir);
+  return walk(canonical)
+    .map((p) => relative(canonical, p).split(sep).join('/'))
+    .filter((rel) => TARGET_ENRICHMENT_ASSETS[rel] !== undefined && !isEnrichmentAsset(rel, canonical))
+    .sort()
+    .map((path) => ({ skill, kind: 'misplaced-enrichment-asset', path, canonical }));
+}
+
+function comparePeers(
+  copies: readonly string[],
+  exclusions: ReadonlyMap<string, ReadonlySet<string>> = new Map(),
+): { driftFiles: number; missingFiles: number; totalFiles: number } {
+  const excluded = (copy: string, rel: string): boolean => exclusions.get(copy)?.has(rel.split(sep).join('/')) === true;
   const relFiles = new Set<string>();
   for (const c of copies) for (const f of walk(c)) {
     const rel = relative(c, f);
-    if (isEnrichmentAsset(rel, c)) continue;
+    if (isEnrichmentAsset(rel, c) || excluded(c, rel)) continue;
     relFiles.add(rel);
   }
 
@@ -195,7 +239,9 @@ function comparePeers(copies: readonly string[]): { driftFiles: number; missingF
     const hashes = new Set<string>();
     for (const c of copies) {
       const p = join(c, rel);
-      if (existsSync(p)) hashes.add(md5(p));
+      // An excluded canonical file is absent from its content; another package's same path
+      // still contributes to the union and must compare as an extra file.
+      if (!excluded(c, rel) && existsSync(p)) hashes.add(md5(p));
       else {
         missingFiles++;
         hashes.add('__MISSING__');
@@ -291,7 +337,7 @@ function findSkillDirs(root: string, scope: 'packages' | 'installs' | 'all' = 'a
  * Detect intra-monorepo skill drift: find every skill duplicated across ≥2 locations and report
  * which copies byte-differ. Pure port of `scripts/drift-sweep-skills.mjs`.
  *
- * `result.drifted.length === 0` is the exact condition the CI gate keys on.
+ * Gates must inspect both copy drift and canonical defects.
  */
 export function sweepSkillDrift(root: string, opts: SweepOptions = {}): SweepResult {
   const scope = opts.scope ?? 'all';
@@ -308,16 +354,22 @@ export function sweepSkillDrift(root: string, opts: SweepOptions = {}): SweepRes
 
   let duplicated = 0;
   const drifted: DriftedSkill[] = [];
+  const canonicalDefects: CanonicalDefect[] = [];
   const allowlisted: DriftedSkill[] = [];
 
   for (const [name, unsorted] of [...byName.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    const meta = join(root, 'packages/@dzhechkov/skills-meta', name);
+    const defects = unsorted.includes(meta) ? findCanonicalDefects(meta, name) : [];
+    canonicalDefects.push(...defects);
     if (unsorted.length < 2) continue;
     duplicated++;
     const copies = [...unsorted].sort();
 
     // Per-skill byte-comparison of every copy against each other (extracted to `comparePeers`
     // so the canonical-free `sync-canonical --check` reuses the EXACT same logic).
-    const { driftFiles, missingFiles, totalFiles } = comparePeers(copies);
+    const { driftFiles, missingFiles, totalFiles } = comparePeers(
+      copies, new Map([[meta, new Set(defects.map((d) => d.path))]]),
+    );
 
     if (driftFiles > 0) {
       const entry: DriftedSkill = {
@@ -335,7 +387,7 @@ export function sweepSkillDrift(root: string, opts: SweepOptions = {}): SweepRes
   const byDrift = (a: DriftedSkill, b: DriftedSkill): number => b.driftFiles - a.driftFiles;
   drifted.sort(byDrift);
   allowlisted.sort(byDrift);
-  return { duplicated, drifted, allowlisted };
+  return { duplicated, drifted, canonicalDefects, allowlisted };
 }
 
 /**
@@ -344,6 +396,7 @@ export function sweepSkillDrift(root: string, opts: SweepOptions = {}): SweepRes
  * byte-identity. Pure port of `scripts/sync-canonical-skill.mjs`, extended with a canonical-free path.
  *
  * `check:true` writes NOTHING (`wrote` stays empty) and only reports the drift count.
+ * A canonical defect also prevents all writes, while reporting the same drift as check mode.
  * Default overwrites drifting copies; a subsequent {@link sweepSkillDrift} then reports 0 drift.
  *
  * When NO canonical resolves (`resolvedFrom === 'none'` — no `--from`, no `skills-meta`, no `--auto`):
@@ -372,12 +425,13 @@ export function syncCanonicalSkill(root: string, skill: string, opts: SyncCanoni
     if (check) {
       // CANONICAL-FREE peer check: are the copies byte-identical to EACH OTHER? (<2 ⇒ vacuously so.)
       const drifted = allCopies.length < 2 ? 0 : comparePeers(allCopies).driftFiles;
-      return { canonical: '', canonicalExists: false, resolvedFrom, copies: allCopies.length, synced: 0, drifted, wrote: [] };
+      return { canonical: '', canonicalExists: false, resolvedFrom, copies: allCopies.length, synced: 0, drifted, canonicalDefects: [], wrote: [] };
     }
     // Bare WRITE with no resolvable canonical → REFUSE. Mutates nothing (`wrote:[]` proves it).
-    return { canonical: '', canonicalExists: false, resolvedFrom, copies: allCopies.length, synced: 0, drifted: 0, wrote: [] };
+    return { canonical: '', canonicalExists: false, resolvedFrom, copies: allCopies.length, synced: 0, drifted: 0, canonicalDefects: [], wrote: [] };
   }
 
+  const canonicalDefects = findCanonicalDefects(canonical, skill);
   const canonFiles = withoutEnrichmentNames(walk(canonical).map((p) => relative(canonical, p))).sort();
 
   // Every <skill>/ dir except the canonical itself.
@@ -403,7 +457,7 @@ export function syncCanonicalSkill(root: string, skill: string, opts: SyncCanoni
     if (!differs) continue;
     drifted++;
 
-    if (check) continue; // report only — write NOTHING
+    if (check || canonicalDefects.length > 0) continue; // check or refusal — write NOTHING
 
     // Overwrite: remove extra files, then copy every canonical file byte-for-byte.
     for (const f of copyFiles) if (!canonFiles.includes(f)) rmSync(join(copy, f));
@@ -417,5 +471,5 @@ export function syncCanonicalSkill(root: string, skill: string, opts: SyncCanoni
     wrote.push(copy);
   }
 
-  return { canonical, canonicalExists: true, resolvedFrom, copies: copies.length, synced, drifted, wrote };
+  return { canonical, canonicalExists: true, resolvedFrom, copies: copies.length, synced, drifted, canonicalDefects, wrote };
 }

package/src/statusline.ts

@@ -19,7 +19,7 @@ import { basename, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 
 import { listBrain } from './brain.js';
-import { withNamedLockSync } from './named-lock.js';
+import { withProjectLockSync } from './named-lock.js';
 import { RECALL_USAGE_LOG_RELATIVE, aggregateRecallUsage, parseRecallUsageLog } from './recall-usage.js';
 import { countLearningStoreRowsReadonly, countSqliteRowsReadonly } from './store-counts.js';
 import {
@@ -585,7 +585,7 @@ export function writeFeatureAdrStateDetailed(
     // half of the lock test can reproduce the lost update. Shipped callers never pass it.
     const written = input._unsafeSkipLock === true
       ? transition()
-      : withNamedLockSync(root, 'fa-phase-slot', transition);
+      : withProjectLockSync(root, 'fa-phase-slot', transition);
     return { state: written };
   } catch (err) {
     // A refusal is REPORTED, never mistaken for success. A lock timeout before the callback proves

package/src/store-guard.ts

@@ -13,7 +13,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSy
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 
-import { withNamedLockSync } from './named-lock.js';
+import { withDirLockSync } from './named-lock.js';
 
 export const STORE_GUARD_VERSION = 1 as const;
 
@@ -256,7 +256,7 @@ export function writeStoreMark(
   validateObservation(observation);
   mkdirSync(guardRoot, { recursive: true, mode: 0o700 });
 
-  return withNamedLockSync(guardRoot, `store-guard-${basename(path, '.json')}`, () => {
+  return withDirLockSync(guardRoot, `store-guard-${basename(path, '.json')}`, () => {
     const previous = readStoreMark(project);
     if (options.expectedPreviousLexicalSource !== undefined
       && previous?.lexicalSource !== options.expectedPreviousLexicalSource) {
@@ -295,7 +295,7 @@ export function resetStoreMark(projectRoot: string, observation: StoreMarkObserv
     throw new Error('store guard reset requires command dz store-guard --reset');
   }
   mkdirSync(guardRoot, { recursive: true, mode: 0o700 });
-  return withNamedLockSync(guardRoot, `store-guard-${basename(path, '.json')}`, () => {
+  return withDirLockSync(guardRoot, `store-guard-${basename(path, '.json')}`, () => {
     const previous = readStoreMark(project);
     const before: StoreCountSnapshot = {
       lexicalRows: previous?.lexicalMax ?? observation.lexicalRows,