@dzhechkov/harness-core 0.8.40 → 0.8.41

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,

package/src/store-lock.ts

@@ -57,7 +57,7 @@
  * one is honoured as held, same as any other lock.
  */
 
-import { mkdirSync, rmSync, statSync } from 'node:fs';
+import { existsSync, rmSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { lockSync } from 'proper-lockfile';
 
@@ -71,6 +71,23 @@ const MIN_STALE_MS = 2_000;
 /** Highest accepted environment override; keeps proper-lockfile's heartbeat timer in range. */
 const MAX_STALE_MS = 600_000;
 
+/** A store exists exactly when the project's .dz entry exists. */
+export function storeExists(projectRoot: string): boolean {
+  return existsSync(join(projectRoot, '.dz'));
+}
+
+/** Refusing a store-scoped lock must never seed a store. */
+export class StoreAbsentError extends Error {
+  readonly code = 'ESTOREABSENT';
+  constructor(readonly root: string, readonly lock: string) {
+    super(
+      `no store at ${root} — the lock ${lock} was not taken and nothing was created; ` +
+      'run `dz init` there, or pass --project <the real project root>',
+    );
+    this.name = 'StoreAbsentError';
+  }
+}
+
 /** Path of the lock guarding a project's pattern store (a DIRECTORY when held). */
 export function storeLockPath(projectRoot: string): string {
   return join(projectRoot, '.dz', 'store.lock');
@@ -201,8 +218,8 @@ export async function withStoreLock<T>(
   fn: () => Promise<T>,
   opts: StoreLockOptions = {},
 ): Promise<T> {
+  if (!storeExists(projectRoot)) throw new StoreAbsentError(projectRoot, 'store');
   const { staleMs, timeoutMs, pollMs } = resolveOpts(opts);
-  mkdirSync(join(projectRoot, '.dz'), { recursive: true });
   const started = Date.now();
   const deadline = started + timeoutMs;
   let compromised: Error | undefined;
@@ -240,8 +257,8 @@ export function withStoreLockSync<T>(
   fn: () => T,
   opts: StoreLockOptions = {},
 ): T {
+  if (!storeExists(projectRoot)) throw new StoreAbsentError(projectRoot, 'store');
   const { staleMs, timeoutMs, pollMs } = resolveOpts(opts);
-  mkdirSync(join(projectRoot, '.dz'), { recursive: true });
   const started = Date.now();
   const deadline = started + timeoutMs;
   let compromised: Error | undefined;

package/src/test-receipt.ts

@@ -0,0 +1,106 @@
+/**
+ * Квитанция зелёного прогона: «эта область исходников была протестирована ИМЕННО в этом виде».
+ *
+ * ЗАЧЕМ ЭТО ЕСТЬ. Два процессных грабля повторялись месяцами и повторились снова 21.09 ПОСЛЕ того,
+ * как напоминание о них было поднято: «объявил сделанным без проверки» (пять случаев) и «коммит без
+ * прогона тестов» (шесть). Напоминание — слой суждения, и он молчит, когда отказывает. Владелец
+ * согласился поднять проверку на слой 1, но с условием: коммиты должны остаться дешёвыми. Поэтому
+ * проверка стоит не на коммите, а на ПУШЕ, и спрашивает не «прогони тесты», а квитанцию.
+ *
+ * ПОЧЕМУ ПО ОБЛАСТЯМ, А НЕ ЦЕЛИКОМ. ИЗМЕРЕНО 21.09: полный прогон набора harness-cli на этой машине
+ * не завершается — надзиратель фоновых задач убивает его по памяти при любом дроблении. Гейт,
+ * требующий квитанцию ПОЛНОГО прогона, заблокировал бы каждый push навсегда. Квитанция покрывает
+ * названные области, и отказ касается только тех, что изменились без покрытия.
+ *
+ * ЧЕГО ЭТА ПРОВЕРКА НЕ ОБЕЩАЕТ, и это сказано здесь, а не в отчёте потом:
+ *  · она не запускает тесты и не знает, ХОРОШИ ли они — только что прогон был и был зелёным;
+ *  · она сравнивает СОДЕРЖИМОЕ рабочего дерева, а не набор пушимых коммитов;
+ *  · она ничего не говорит о коммитах, которые никогда не пушат;
+ *  · зелёный прогон ДРУГОЙ области не покрывает изменённую — это и есть смысл разбиения.
+ */
+
+/** Одна запись журнала квитанций. Пишется ТОЛЬКО наблюдателем, видевшим код возврата 0. */
+export interface TestReceipt {
+  readonly v: 1;
+  /** Когда прогон закончился, ISO-8601. */
+  readonly ts: string;
+  /** Что именно было запущено — для сообщения об отказе, чтобы читатель мог повторить. */
+  readonly command: string;
+  /** Область → отпечаток её содержимого на момент зелёного прогона. */
+  readonly scopes: Readonly<Record<string, string>>;
+}
+
+/** Состояние одной области в вердикте. */
+export interface TestReceiptScopeState {
+  readonly scope: string;
+  /** Отпечаток содержимого СЕЙЧАС. */
+  readonly digest: string;
+  /**
+   * `never` — область не встречается ни в одной квитанции: прогона не было вовсе.
+   * `changed` — квитанции есть, но ни одна не покрывает текущее содержимое.
+   */
+  readonly why: 'never' | 'changed';
+  /** Время самой свежей квитанции, покрывавшей эту область в ЛЮБОМ виде; null при `never`. */
+  readonly lastGreenAt: string | null;
+}
+
+export type TestReceiptVerdict =
+  | { readonly state: 'covered'; readonly scopes: readonly string[] }
+  | { readonly state: 'stale'; readonly uncovered: readonly TestReceiptScopeState[] }
+  | { readonly state: 'not-established'; readonly reason: string };
+
+/**
+ * Чистое решение. Ничего не читает и не запускает — отпечатки и журнал подаёт вызывающий.
+ *
+ * Три исхода, а не два, намеренно: «не установлено» — это НЕ «покрыто». Гейт, выводящий пропуск из
+ * пустого входа, тихо ломается на каждом новом способе получить пустой вход.
+ */
+export function decideTestReceipt(input: {
+  readonly current: Readonly<Record<string, string>>;
+  readonly receipts: readonly TestReceipt[];
+}): TestReceiptVerdict {
+  const current = input.current ?? {};
+  const scopes = Object.keys(current).sort();
+  if (scopes.length === 0) {
+    return { state: 'not-established', reason: 'ни одна наблюдаемая область не разрешилась — проверка была бы вакуумной' };
+  }
+  for (const scope of scopes) {
+    if (typeof current[scope] !== 'string' || current[scope] === '') {
+      return { state: 'not-established', reason: `отпечаток области ${scope} не вычислен — вердикт не о чем выносить` };
+    }
+  }
+
+  const receipts = (Array.isArray(input.receipts) ? input.receipts : []).filter(
+    (r): r is TestReceipt => !!r && typeof r === 'object' && r.scopes !== null && typeof r.scopes === 'object',
+  );
+
+  const uncovered: TestReceiptScopeState[] = [];
+  for (const scope of scopes) {
+    const digest = current[scope]!;
+    let seenAt: string | null = null;
+    let covered = false;
+    for (const receipt of receipts) {
+      const recorded = receipt.scopes[scope];
+      if (typeof recorded !== 'string') continue;
+      if (typeof receipt.ts === 'string' && (seenAt === null || receipt.ts > seenAt)) seenAt = receipt.ts;
+      if (recorded === digest) { covered = true; break; }
+    }
+    if (!covered) uncovered.push({ scope, digest, why: seenAt === null ? 'never' : 'changed', lastGreenAt: seenAt });
+  }
+
+  return uncovered.length === 0 ? { state: 'covered', scopes } : { state: 'stale', uncovered };
+}
+
+/** Одна строка для человека. Отказ обязан говорить, ЧТО запустить, а не только что всё плохо. */
+export function renderTestReceiptVerdict(verdict: TestReceiptVerdict): string {
+  if (verdict.state === 'covered') {
+    return `test-receipt: покрыто — ${verdict.scopes.length} област(и) в том же виде, в каком были зелёными`;
+  }
+  if (verdict.state === 'not-established') {
+    return `test-receipt: НЕ УСТАНОВЛЕНО — ${verdict.reason}. Это не пропуск и не отказ по существу`;
+  }
+  const lines = verdict.uncovered.map((item) => item.why === 'never'
+    ? `  · ${item.scope}: зелёного прогона не было НИ РАЗУ`
+    : `  · ${item.scope}: изменилась после последнего зелёного прогона (${item.lastGreenAt})`);
+  return [`test-receipt: НЕ ПОКРЫТО — ${verdict.uncovered.length} област(и):`, ...lines].join('\n');
+}

package/src/workflow-run.ts

@@ -42,6 +42,7 @@ import {
 import { classifyFailure, errSnap, gateVerdict, joinRegion, stepContractLines, type JoinOutcome } from './loop-run-semantics.js';
 import { checkpointInputHash, decideCheckpointResume, parseCheckpointRead, serializeCheckpoint } from './feature-adr-checkpoints.js';
 import { modelFamily, type BridgeFamily } from './qe-bridge.js';
+import { buildReqeDebt } from './reqe.js';
 import { CODEX_EXEC_XHIGH_TIMEOUT_MS, defangGateEchoes, type DispatchResult, type Dispatcher } from './workflow-run-dispatch.js';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -1203,19 +1204,17 @@ export async function runWorkflow(inputs: RunnerInputs, pre: PreflightOk, deps:
 
   // a waived same-family QE step owes a machine debt, not a doc instruction (the FR-2.9 precedent)
   for (const w of pre.qeWaivers) {
-    // The FR-2.9 `reqe-due-1` shape VERBATIM (`reqe.ts` parseReqeDebt), because the debt is only
-    // real if `dz reqe` can read it — a record in a shape the reader rejects is a promise, not a
-    // debt. `qeFamily` equals `coderFamily` here: that identity IS the waiver.
-    store.writeReqeDebt({
-      schema: 'reqe-due-1',
+    // Use the shared builder so the waiver stays readable by every debt consumer.
+    store.writeReqeDebt(buildReqeDebt({
       slug: deps.slug ?? inputs.runId,
-      coderFamily: inputs.coderFamily,
-      qeFamily: inputs.coderFamily,
+      coderUsed: inputs.coderFamily,
+      qeReviewerUsed: inputs.coderFamily,
       qeGrade: null,
+      cause: 'same-family-fallback',
       reason: `dz workflow run ${inputs.runId}: step ${w.step} (x-role: qe) resolved to the CODER family ${inputs.coderFamily} and ran under --allow-same-family-qe — the cross-family guard was consciously suspended, so an independent review is OWED`,
       emittedAt: startedAt,
       runStamp: `${inputs.runId}:${pre.execFp.slice(0, 16)}`,
-    });
+    }));
   }
 
   // the PROBED ids (established above, before the resume decision) become this run's resolution