@dzhechkov/harness-core 0.3.149 → 0.4.1

package/src/no-stubs.ts

@@ -0,0 +1,204 @@
+// `no-stubs` — a deterministic layer-1 scan for unfinished-stub markers left in CHANGED files
+// (backlog 0b403a0106103901, Karpathy-Michaels rule XI). `dz claim-check` catches false CLAIMS in
+// prose; an unfinished stub in code was, until this rule, caught only by a QE agent's judgment
+// (layer 4 on the cost-of-detection ladder). A five-line grep is layer 1 — cheap, deterministic,
+// silent-proof — so that is where this check lives.
+//
+// MEASURED before design (2026-08-10, this repo): a case-INSENSITIVE whole-tree scan over
+// packages/@dzhechkov/*/{src,lib,skills} yields 32 hits and over {test,fixtures} another 25 — the
+// clear majority ancient and legitimate (prose "placeholder", a `todo` keyword list, `xxx` in an
+// example URL). Two design decisions fall straight out of that measurement:
+//   1. SCOPE = the CHANGE-SET, not the tree. The gate catches what YOU left in THIS change; it does
+//      not relitigate 25 ancient fixture markers. The change-set is the same working-tree
+//      `git status --porcelain` diff the readme-first rule and the template-rule `change` fact
+//      already use — one notion of "changed", not a third.
+//   2. CASE-SENSITIVE bare markers. Dropping case halves the hits (32 → 16) and EVERY line the
+//      relaxation would add was inspected and found to be prose, not a stub. The uppercase
+//      convention is the stub convention; lowercase is English.
+//
+// SELF-EXEMPTION IS STRUCTURAL, NOT A PATH SKIP: every marker below is assembled from fragments at
+// module load, so this file — and any file that builds its patterns the same way — contains no
+// literal marker for the scan to find. A test proves the scan of this very source yields nothing.
+//
+// PURE: no filesystem, no child_process. The caller (CLI / guard facts gatherer) hands in paths,
+// contents, and config waivers; everything here is deterministic string work.
+//
+// ── KNOWN LIMITS (conscious trade-offs — the rule SAYS them rather than implying totality) ──────
+// A guarantee the code asserts but does not hold is worse than an honest limit. Each item below is
+// a DECISION, not an oversight; none is silently patched around.
+//
+// • WHOLE-LINE inline waiver (FN-2). The waiver token exempts the ENTIRE line it appears on
+//   (indexOf-based, no position check) — any line can be silenced by appending the token. The
+//   defence is AUDITABILITY, not prevention: the token is a fixed greppable string, so every
+//   silencing is one grep away. That is a layer-4 defence (reviewer judgment over grep output) by
+//   the cost-of-detection ladder, and it is named as such here on purpose.
+// • REASON QUALITY is not judged (FN-6). A junk reason ('.', 'x') satisfies the reason
+//   requirement. The design stops FORGETTING a reason, not FAKING one — a deterministic layer
+//   cannot judge whether a reason is honest; that is review-plane work.
+// • MARKDOWN FENCE MODEL is a single boolean toggle (FN-4). It cannot model CommonMark: a
+//   mismatched pair of tilde/backtick fence styles, an INDENTED fence, an unclosed fence running
+//   to EOF (everything after it reads as fenced ⇒ skipped), and a marker sitting on the fence
+//   info-string line itself are all mis-scoped. Good enough for the docs this repo writes; not a
+//   CommonMark parser and not claimed to be one.
+// • GIT-QUOTED PATHS are not decoded (FN-3). A path `git status --porcelain` quotes (spaces,
+//   non-ASCII under core.quotePath=true — the default) arrives here with quote characters baked
+//   in, matches no real file, and is therefore NOT scanned. Fail-open by shape, and invisible per
+//   file; the aggregate skipped-files note is the only trace when contents were also not gathered.
+// • EXTENSION ALLOWLIST is a TS-monorepo set (FN-8). Extensionless bin scripts, Dockerfile,
+//   Makefile, .txt/.html/.css/.vue/.svelte/.c/.cpp/.php/.toml/.sql/.ps1/.kt/.swift are NOT
+//   scanned. MED risk if this rule template ships into a polyglot repo — extend
+//   STUB_SCAN_EXTENSIONS there; the list is exported and testable for exactly that reason.
+// • STAGED-BUT-NOT-WORKTREE content is not read (FN-5). The gatherer reads the WORKING TREE; a
+//   change staged in the index but reverted in the worktree scans as the worktree text. Design-
+//   consistent for the publish op, which packs the worktree — the index never ships.
+// • CONFIG WAIVERS match the EXACT repo-relative path string. No normalization, no globs: a
+//   waiver for a path spelled differently than git spells it simply does not match, and the
+//   finding FIRES. Errs toward firing — the safe side for an exemption mechanism.
+
+/**
+ * The bare stub markers, ASSEMBLED so this module never fires on itself. Matched case-SENSITIVELY
+ * (measured: case-insensitivity doubles hits and adds only prose) with hard word boundaries on both
+ * sides, so a marker embedded in a word (a codename, a longer identifier) does not fire.
+ */
+export const STUB_MARKERS: readonly string[] = [
+  'TO' + 'DO',
+  'FIX' + 'ME',
+  'HA' + 'CK',
+  'XX' + 'X',
+  'PLACE' + 'HOLDER',
+];
+
+/**
+ * Stub PHRASES: matched case-insensitively (a phrase is English, not a convention), with letter
+ * boundaries. Assembled for the same self-exemption reason.
+ */
+export const STUB_PHRASES: readonly string[] = ['imple' + 'ment later'];
+
+// One regex per class, built once. `(?<![A-Za-z0-9_])` / `(?![A-Za-z0-9_])`: a marker glued to a
+// word character on either side is part of an identifier/hash/codename, not a stub. XXXX therefore
+// does NOT match the three-letter marker (its neighbours are word chars), and lowercase variants of
+// the bare markers never match at all.
+const BARE_RE = new RegExp('(?<![A-Za-z0-9_])(' + STUB_MARKERS.join('|') + ')(?![A-Za-z0-9_])');
+const PHRASE_RE = new RegExp('(?<![A-Za-z])(' + STUB_PHRASES.join('|').replace(/ /g, '\\s+') + ')(?![A-Za-z])', 'i');
+
+/**
+ * The inline waiver token: a line carrying `no-stubs: <reason>` is exempt — WITH a non-empty reason.
+ * A reasonless waiver is REFUSED LOUDLY (its own finding): an exemption you cannot explain is a
+ * silent allowlist, the recurring defect class this repo keeps re-learning. The reason-required
+ * shape follows the `dz feature-adr-setup --guards` waiver precedent (`waivers: [{path, reason}]`,
+ * "a waiver without a reason is itself a violation").
+ */
+const WAIVER_TOKEN = 'no-stubs:';
+
+/**
+ * File extensions the scan reads. EXPLICIT and testable — never a silent glob. Fixture/test paths
+ * are NOT auto-exempt: a marker you just added to a fixture is still a decision, and the waiver is
+ * where that decision gets its reason.
+ */
+export const STUB_SCAN_EXTENSIONS: readonly string[] = [
+  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+  '.py', '.go', '.rs', '.java', '.rb', '.sh', '.bash',
+  '.md', '.mdx', '.markdown',
+  '.yml', '.yaml', '.json',
+];
+
+/** Is this path one the stub scan reads? (extension allowlist, case-insensitive on the extension) */
+export function scannableStubPath(path: unknown): boolean {
+  if (typeof path !== 'string' || path.length === 0) return false;
+  const lower = path.toLowerCase();
+  return STUB_SCAN_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+
+export interface StubFinding {
+  readonly path: string;
+  /** 1-based line number. */
+  readonly line: number;
+  readonly kind: 'marker' | 'reasonless-waiver';
+  /** which marker/phrase matched (for 'marker'), or the refusal text (for 'reasonless-waiver'). */
+  readonly detail: string;
+}
+
+/** A config waiver: path-keyed, reason MANDATORY. A reasonless entry is refused, never honoured. */
+export interface StubWaiver {
+  readonly path?: string;
+  readonly reason?: string;
+}
+
+function isMarkdown(path: string): boolean {
+  const lower = path.toLowerCase();
+  return lower.endsWith('.md') || lower.endsWith('.mdx') || lower.endsWith('.markdown');
+}
+
+/** Mask inline `code spans` with spaces (length-preserving, so line/column geometry survives). */
+function maskInlineCode(line: string): string {
+  return line.replace(/`[^`]*`/g, (m) => ' '.repeat(m.length));
+}
+
+/**
+ * Scan ONE file's text. Case-sensitive bare markers + case-insensitive phrases, word-bounded.
+ * Markdown gets PROSE scoping: fenced code blocks and inline backtick spans are QUOTES of a marker,
+ * not stubs (the claim-check backtick-literal convention) — a doc explaining this very gate scans
+ * clean, while a naked stub line in doc prose still fires. Code files are scanned in full: a marker
+ * a code file must legitimately carry (another gate's source, a fixture) takes an inline
+ * `no-stubs: <reason>` waiver — visible, reasoned, greppable.
+ */
+export function scanStubs(path: string, text: unknown): StubFinding[] {
+  if (typeof text !== 'string' || text.length === 0) return [];
+  const md = isMarkdown(path);
+  const out: StubFinding[] = [];
+  let inFence = false;
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i]!;
+    if (md && /^\s*(```|~~~)/.test(raw)) { inFence = !inFence; continue; }
+    if (md && inFence) continue;
+    const line = md ? maskInlineCode(raw) : raw;
+
+    // Inline waiver first: with a reason ⇒ the line is exempt; without one ⇒ refuse loudly AND
+    // leave the marker finding in place (a refused waiver must not half-work).
+    const w = line.indexOf(WAIVER_TOKEN);
+    if (w >= 0) {
+      const reason = line.slice(w + WAIVER_TOKEN.length).replace(/(\*\/|-->|#>)\s*$/, '').trim();
+      if (reason.length > 0) continue;
+      out.push({ path, line: i + 1, kind: 'reasonless-waiver', detail: `inline waiver ("${WAIVER_TOKEN}") carries NO reason — refused; a waiver you cannot explain is a silent allowlist` });
+    }
+
+    const bare = BARE_RE.exec(line);
+    if (bare && bare[1] !== undefined) { out.push({ path, line: i + 1, kind: 'marker', detail: bare[1] }); continue; }
+    const phrase = PHRASE_RE.exec(line);
+    if (phrase && phrase[1] !== undefined) out.push({ path, line: i + 1, kind: 'marker', detail: phrase[1] });
+  }
+  return out;
+}
+
+/**
+ * The aggregate check the guard rule calls: scan the CHANGED files whose contents were gathered,
+ * then apply config waivers. Missing contents for a changed file ⇒ that file reports nothing
+ * (fail-open on missing evidence — the standing guard contract; a deleted file has no contents).
+ *
+ * Config-waiver semantics: an entry with a non-empty `path` AND a non-empty `reason` exempts that
+ * exact repo-relative path. An entry with a path but NO reason is REFUSED as its own finding and
+ * exempts nothing. An entry with no path at all is inert garbage and is ignored (there is nothing
+ * it could exempt, and inventing a finding for it would punish a stray comma).
+ */
+export function checkNoStubs(
+  files: readonly string[],
+  contents: Readonly<Record<string, string>> | undefined,
+  waivers: readonly StubWaiver[] | undefined,
+): StubFinding[] {
+  const out: StubFinding[] = [];
+  const waived = new Set<string>();
+  for (const w of Array.isArray(waivers) ? waivers : []) {
+    if (!w || typeof w !== 'object' || typeof w.path !== 'string' || w.path.trim() === '') continue;
+    const reason = typeof w.reason === 'string' ? w.reason.trim() : '';
+    if (reason.length > 0) waived.add(w.path);
+    else out.push({ path: w.path, line: 0, kind: 'reasonless-waiver', detail: 'config waiver (stubWaivers) carries NO reason — refused; add a reason or remove the entry' });
+  }
+  for (const f of Array.isArray(files) ? files : []) {
+    if (!scannableStubPath(f) || waived.has(f)) continue;
+    const text = contents?.[f];
+    if (typeof text !== 'string') continue; // no evidence gathered — fail-open, never guessed
+    out.push(...scanStubs(f, text));
+  }
+  return out;
+}

package/src/package-skill-layouts.ts

@@ -0,0 +1,107 @@
+/**
+ * Package skill-layout resolution — where an installed npm package keeps its skills.
+ *
+ * `dz install <pkg>` (and, later, `dz init`/`dz registry` — see the backlog note below)
+ * must find `SKILL.md` skill dirs inside an npm package. Packages in the wild ship three
+ * on-disk arrangements; before this module existed, `cmdInstall` hard-coded exactly one
+ * (`flat`), so every npx-init pack (`templates/.claude/skills/…`) and bare-`skills/`
+ * pack resolved to "no SKILL.md files found" despite carrying valid skills.
+ *
+ * DESIGN RULE — ordered allowlist, NEVER a recursive find. A recursive "find any
+ * SKILL.md" walk would resolve decoys that must stay invisible (both MEASURED in the
+ * feature's layout census, `features/dz-install-npx-init/05_architecture.md` §3):
+ *
+ *   - `adapter-claude/test/fixtures/<id>/SKILL.md` — a test fixture, not a shipped skill;
+ *   - `health-advisor/base/skills/base/<id>/SKILL.md` — a vendored mirror of another
+ *     pack's skills (skills-analyst-manual); resolving it would double-install them.
+ *
+ * The allowlist is three fixed relative paths with no walk, so those decoys are
+ * structurally unreachable (they are not on the probe list) rather than filtered out.
+ * Any future recursive extension MUST re-introduce exclusion logic for both cases.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { discoverSkillIds } from './skills.js';
+
+/** A known on-disk arrangement of skills inside an npm package. */
+export type PackageSkillLayout =
+  | 'flat' //          <pkg>/<skill>/SKILL.md                           — classic skills-* pack
+  | 'npx-template' //  <pkg>/templates/.claude/skills/<skill>/SKILL.md  — npx-init pack
+  | 'skills-dir'; //   <pkg>/skills/<skill>/SKILL.md                    — bare skills dir
+
+/** One resolved skills root inside a package. */
+export interface PackageSkillRoot {
+  readonly layout: PackageSkillLayout;
+  /** Absolute dir to hand to `runInit({ skillsDir })` — its children are skill dirs. */
+  readonly dir: string;
+  /** Skill ids discovered under `dir` (sorted, via {@link discoverSkillIds}). */
+  readonly ids: readonly string[];
+  /**
+   * True iff the matched root's parent carries sibling non-skill component dirs the
+   * resolver does NOT install (e.g. `templates/.claude/commands` next to
+   * `templates/.claude/skills` in an npx-init pack). `dz install` uses this to disclose,
+   * honestly, that `npx -y <pkg> init` installs a larger kit. Always `false` for the
+   * `flat` layout (the package root's other dirs — `bin/`, `src/` — are not components).
+   */
+  readonly hasCompanionAssets: boolean;
+}
+
+/**
+ * Ordered layout probe list. ORDER IS THE CONTRACT — first non-empty wins.
+ *
+ * `flat` is probed first so a classic pack can never be re-interpreted; `npx-template`
+ * before `skills-dir` matches the measured census (13 vs 2 packages). Extending support
+ * for a new layout is a data edit here, not new control flow.
+ */
+export const PACKAGE_SKILL_LAYOUTS: readonly { readonly layout: PackageSkillLayout; readonly rel: string }[] = [
+  { layout: 'flat', rel: '.' },
+  { layout: 'npx-template', rel: 'templates/.claude/skills' },
+  { layout: 'skills-dir', rel: 'skills' },
+];
+
+/** Does the matched skills root have sibling component dirs (commands/hooks/agents…)? */
+function companionAssetsPresent(skillsRoot: string): boolean {
+  const parent = dirname(skillsRoot);
+  if (!existsSync(parent)) return false;
+  try {
+    return readdirSync(parent, { withFileTypes: true }).some(
+      (entry) => entry.isDirectory() && entry.name !== 'skills',
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve the skills root of an installed npm package.
+ *
+ * Probes {@link PACKAGE_SKILL_LAYOUTS} in order; the FIRST layout with at least one
+ * `<root>/<id>/SKILL.md` wins, and exactly one root is returned (`[root]`). Returns `[]`
+ * when the package carries no skills in ANY known layout — the caller MUST treat `[]`
+ * as an error (see `cmdInstall`'s exit code). Single-root is deliberate (feature
+ * dz-install-npx-init, plan AM-4): no package today has skills in two allowlisted
+ * layouts simultaneously, so multi-root install semantics would be untested dead code.
+ * The array return type keeps the door open without committing to a merge policy.
+ *
+ * Pure, filesystem-read-only, synchronous, never throws on missing/unreadable dirs.
+ */
+export function resolvePackageSkillRoots(pkgDir: string): readonly PackageSkillRoot[] {
+  for (const { layout, rel } of PACKAGE_SKILL_LAYOUTS) {
+    const dir = rel === '.' ? pkgDir : join(pkgDir, rel);
+    const ids = discoverSkillIds(dir);
+    if (ids.length === 0) continue;
+    return [
+      {
+        layout,
+        dir,
+        ids,
+        hasCompanionAssets: layout === 'npx-template' && companionAssetsPresent(dir),
+      },
+    ];
+  }
+  return [];
+}

package/src/patterns.ts

@@ -30,6 +30,7 @@ import { JsonFileBackend, SqliteBackend, harvestDreamPatterns, isNoiseInsight, t
 import { resolveAgentdbPath } from './agentdb-index.js';
 import type { VectorEntry } from './vector-tier.js';
 import { rankLessonsByDelta, type LessonHistory } from './safla-delta.js';
+import { withStoreLock, withStoreLockSync, StoreLockTimeoutError, StoreLockCompromisedError } from './store-lock.js';
 
 /** A learned pattern as written by `dz teach` to `.dz/patterns.jsonl`. */
 export interface PatternRecord {
@@ -304,8 +305,35 @@ export function computePatternBoost(
 
 /* ------------------------------------------------------------------ */
 /*  Tier-2: the unified @dzhechkov/memory store (ADR-005)              */
+/*                                                                     */
+/*  WRITER INVENTORY (store-wide locking — review finding 5).          */
+/*  Every function that WRITES the JSON store (.dz/memory/patterns.json)
+/*  holds the store lock for its whole read-modify-write:              */
+/*    - recordPattern        (JSON branch)   withStoreLock             */
+/*    - reinforcePattern                     withStoreLock             */
+/*    - updateReinforcementState             withStoreLock             */
+/*    - promotePatterns                      withStoreLock             */
+/*    - consolidateSessions  (JSON branch)   withStoreLock             */
+/*    - pruneNoisePatterns   (JSON tier, live runs) withStoreLockSync  */
+/*    - removePatternsByIds  (JSON tier)     withStoreLockSync         */
+/*  Deliberately OUT of scope (reasoning):                             */
+/*    - the SQLite tier — better-sqlite3 transactions serialize it;    */
+/*    - snapshotStore — reads the atomically-renamed store file and    */
+/*      writes a DIFFERENT file, so it cannot lose store updates;      */
+/*    - the consolidate watermark + sessions.jsonl / patterns.jsonl    */
+/*      appends — separate append-only/idempotent files (an older      */
+/*      watermark merely causes an idempotent re-scan, dedup by        */
+/*      deterministic ids);                                            */
+/*    - dry-run prune paths — read-only by construction.               */
 /* ------------------------------------------------------------------ */
 
+/** Map a lock failure to the best-effort writers' `{ error }` channel (still loud —
+ * the caller SEES the failure and nothing was silently dropped), rethrow anything else. */
+function lockErrorMessage(err: unknown): string {
+  if (err instanceof StoreLockTimeoutError || err instanceof StoreLockCompromisedError) return err.message;
+  throw err;
+}
+
 /** Path of the JSON store (the deterministic fallback backend). */
 function storePath(projectRoot: string): string {
   return join(projectRoot, '.dz', 'memory', 'patterns.json');
@@ -508,6 +536,9 @@ export function loadStoreRecords(projectRoot: string): MemoryRecord[] {
   }
 }
 
+/** Write one record through the backend cascade. CALLER HOLDS THE STORE LOCK — every
+ * caller (reinforce / updateReinforcementState / promote) wraps its whole read-modify-write
+ * in `withStoreLock`; taking the (non-reentrant) lock here as well would deadlock. */
 async function putStoreRecord(projectRoot: string, rec: MemoryRecord): Promise<{ ok: true } | { error: string }> {
   const { sqliteBackend } = readLearningConfig(projectRoot);
   if (sqliteBackend !== 'json') {
@@ -543,6 +574,16 @@ export interface ReinforcePatternResult {
 }
 
 export async function reinforcePattern(projectRoot: string, dzIdOrText: string, opts: { reward?: number; ts?: string; mergedFrom?: readonly string[]; exposure?: boolean } = {}): Promise<ReinforcePatternResult> {
+  // The WHOLE read-modify-write holds the store lock (finding 5): two concurrent
+  // reinforces would otherwise both read uses=N and both write back N+1.
+  try {
+    return await withStoreLock(projectRoot, async () => reinforcePatternLocked(projectRoot, dzIdOrText, opts));
+  } catch (err) {
+    return { ok: false, error: lockErrorMessage(err) };
+  }
+}
+
+async function reinforcePatternLocked(projectRoot: string, dzIdOrText: string, opts: { reward?: number; ts?: string; mergedFrom?: readonly string[]; exposure?: boolean }): Promise<ReinforcePatternResult> {
   const records = loadStoreRecords(projectRoot);
   const rec = records.find((r) => r.id === dzIdOrText || r.text === dzIdOrText);
   if (rec === undefined) return { ok: false, error: `no learned pattern matches ${JSON.stringify(dzIdOrText)}` };
@@ -579,15 +620,21 @@ export async function reinforcePattern(projectRoot: string, dzIdOrText: string,
 }
 
 export async function updateReinforcementState(projectRoot: string, dzId: string, state: ReinforcementState): Promise<ReinforcePatternResult> {
-  const rec = loadStoreRecords(projectRoot).find((r) => r.id === dzId);
-  if (rec === undefined) return { ok: false, error: `no learned pattern matches ${JSON.stringify(dzId)}` };
-  const next: MemoryRecord = {
-    ...rec,
-    metadata: { ...(rec.metadata ?? {}), ...encodeReinforcementState(state) },
-  };
-  const put = await putStoreRecord(projectRoot, next);
-  if ('error' in put) return { ok: false, dzId, error: put.error };
-  return { ok: true, dzId, uses: state.uses };
+  try {
+    return await withStoreLock(projectRoot, async () => {
+      const rec = loadStoreRecords(projectRoot).find((r) => r.id === dzId);
+      if (rec === undefined) return { ok: false, error: `no learned pattern matches ${JSON.stringify(dzId)}` };
+      const next: MemoryRecord = {
+        ...rec,
+        metadata: { ...(rec.metadata ?? {}), ...encodeReinforcementState(state) },
+      };
+      const put = await putStoreRecord(projectRoot, next);
+      if ('error' in put) return { ok: false, dzId, error: put.error };
+      return { ok: true, dzId, uses: state.uses };
+    });
+  } catch (err) {
+    return { ok: false, dzId, error: lockErrorMessage(err) };
+  }
 }
 
 /** Result of a promotion (dz recall --promote). */
@@ -606,22 +653,28 @@ export interface PromoteResult {
  * promoting by exposure would be a self-fulfilling prophecy (ADR).
  */
 export async function promotePatterns(projectRoot: string, dzIds: readonly string[]): Promise<PromoteResult> {
-  const records = loadStoreRecords(projectRoot);
-  const promoted: string[] = [];
-  const notFound: string[] = [];
-  const notQuarantined: string[] = [];
-  for (const id of dzIds) {
-    const rec = records.find((r) => r.id === id);
-    if (rec === undefined) { notFound.push(id); continue; }
-    if (!readQuarantineState(rec).quarantined) { notQuarantined.push(id); continue; }
-    const meta = { ...(rec.metadata ?? {}) };
-    delete meta['qStatus'];
-    delete meta['quarantinedAt'];
-    const put = await putStoreRecord(projectRoot, { ...rec, metadata: meta });
-    if ('error' in put) return { ok: false, promoted, notFound, notQuarantined, error: put.error };
-    promoted.push(id);
+  try {
+    return await withStoreLock(projectRoot, async () => {
+      const records = loadStoreRecords(projectRoot);
+      const promoted: string[] = [];
+      const notFound: string[] = [];
+      const notQuarantined: string[] = [];
+      for (const id of dzIds) {
+        const rec = records.find((r) => r.id === id);
+        if (rec === undefined) { notFound.push(id); continue; }
+        if (!readQuarantineState(rec).quarantined) { notQuarantined.push(id); continue; }
+        const meta = { ...(rec.metadata ?? {}) };
+        delete meta['qStatus'];
+        delete meta['quarantinedAt'];
+        const put = await putStoreRecord(projectRoot, { ...rec, metadata: meta });
+        if ('error' in put) return { ok: false, promoted, notFound, notQuarantined, error: put.error };
+        promoted.push(id);
+      }
+      return { ok: true, promoted, notFound, notQuarantined };
+    });
+  } catch (err) {
+    return { ok: false, promoted: [], notFound: [], notQuarantined: [], error: lockErrorMessage(err) };
   }
-  return { ok: true, promoted, notFound, notQuarantined };
 }
 
 /** One quarantined-and-stale record, surfaced for review (informational — FR-7). */
@@ -867,14 +920,20 @@ export async function recordPattern(projectRoot: string, p: PatternRecord, opts:
       sqlite.close();
     }
   }
-  // JSON fallback
-  const backend = await JsonFileBackend.open(storePath(projectRoot));
-  for (const legacy of readJsonl(join(projectRoot, '.dz', 'patterns.jsonl'), isPatternRecord)) {
-    await backend.put(patternToRecord(legacy));
-  }
-  await backend.put(rec);
-  await backend.save();
-  return backend.count();
+  // JSON fallback. The load-mutate-save below MUST hold the store lock: the backend's
+  // write is atomic (no torn file) but a teach is a read-modify-write, and two that
+  // overlap each write back their own copy of the record set — the later rename wins and
+  // the earlier lesson is silently gone while both processes report success. SQLite does
+  // its own locking and never reaches here.
+  return withStoreLock(projectRoot, async () => {
+    const backend = await JsonFileBackend.open(storePath(projectRoot));
+    for (const legacy of readJsonl(join(projectRoot, '.dz', 'patterns.jsonl'), isPatternRecord)) {
+      await backend.put(patternToRecord(legacy));
+    }
+    await backend.put(rec);
+    await backend.save();
+    return backend.count();
+  });
 }
 
 /** Outcome of a {@link recallPatterns} ranked search (or a hybrid merge — see `vector-tier.ts`). */
@@ -1241,22 +1300,28 @@ export function pruneNoisePatterns(projectRoot: string, opts: { dryRun?: boolean
     }
   }
 
-  // Lexical store, JSON tier (may hold pre-migration copies of the same noise)
-  try {
-    if (existsSync(storePath(projectRoot))) {
-      const backend = JsonFileBackend.openSync(storePath(projectRoot));
-      let removed = 0;
-      for (const r of backend.allSync()) {
-        if (readQuarantineState(r).quarantined) continue; // AM-3: never coupled to noise-prune
-        if (isNoiseInsight(r.text)) {
-          if (!candidates.some((c) => c.id === r.id)) candidates.push({ id: r.id, text: r.text });
-          if (!dryRun) backend.removeSync(r.id);
-          removed += 1;
-        }
+  // Lexical store, JSON tier (may hold pre-migration copies of the same noise).
+  // A LIVE run is a read-modify-write of the whole store file, so it holds the store
+  // lock (finding 5); a dry run reads the atomically-renamed file and is safe unlocked
+  // (and must not error against a merely-busy store).
+  const sweepJsonTier = (): void => {
+    if (!existsSync(storePath(projectRoot))) return;
+    const backend = JsonFileBackend.openSync(storePath(projectRoot));
+    let removed = 0;
+    for (const r of backend.allSync()) {
+      if (readQuarantineState(r).quarantined) continue; // AM-3: never coupled to noise-prune
+      if (isNoiseInsight(r.text)) {
+        if (!candidates.some((c) => c.id === r.id)) candidates.push({ id: r.id, text: r.text });
+        if (!dryRun) backend.removeSync(r.id);
+        removed += 1;
       }
-      if (removed > 0 && !dryRun) void backend.save(); // physically synchronous (writeFileSync under the hood)
-      lexicalRemoved += removed;
     }
+    if (removed > 0 && !dryRun) void backend.save(); // physically synchronous (writeFileSync under the hood)
+    lexicalRemoved += removed;
+  };
+  try {
+    if (dryRun) sweepJsonTier();
+    else withStoreLockSync(projectRoot, sweepJsonTier);
   } catch (err) {
     errors.push(`json store: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -1315,9 +1380,13 @@ export function removePatternsByIds(projectRoot: string, ids: ReadonlySet<string
     }
   }
 
-  // Lexical store, JSON tier (may hold pre-migration copies of the same record)
+  // Lexical store, JSON tier (may hold pre-migration copies of the same record).
+  // Read-modify-write of the whole store file ⇒ holds the store lock (finding 5): an
+  // unlocked remove overlapping a teach would write back a snapshot without the new
+  // lesson. On lock failure NOTHING was written and the error says so.
   try {
-    if (existsSync(storePath(projectRoot))) {
+    withStoreLockSync(projectRoot, () => {
+      if (!existsSync(storePath(projectRoot))) return;
       const backend = JsonFileBackend.openSync(storePath(projectRoot));
       let localRemoved = 0;
       for (const r of backend.allSync()) {
@@ -1328,7 +1397,7 @@ export function removePatternsByIds(projectRoot: string, ids: ReadonlySet<string
       }
       if (localRemoved > 0) void backend.save(); // physically synchronous (writeFileSync under the hood)
       removed += localRemoved;
-    }
+    });
   } catch (err) {
     errors.push(`json store: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -1409,17 +1478,23 @@ export async function consolidateSessions(
       sqlite.close();
     }
   } else {
-    const backend = await JsonFileBackend.open(storePath(projectRoot));
-    const before = await backend.count();
-    let prev = before;
-    for (const d of dreams) {
-      await backend.put(dreamToStoreRecord(d));
-      const now = await backend.count();
-      if (now > prev) newDreams.push(d);
-      prev = now;
-    }
-    await backend.save();
-    added = prev - before;
+    // JSON fallback: the open→put→save below is a read-modify-write of the whole store
+    // file, so it must hold the store lock (finding 5) — a consolidate overlapping a
+    // teach would otherwise overwrite the teach's record and, because the watermark
+    // advances afterwards, make the loss permanent.
+    added = await withStoreLock(projectRoot, async () => {
+      const backend = await JsonFileBackend.open(storePath(projectRoot));
+      const before = await backend.count();
+      let prev = before;
+      for (const d of dreams) {
+        await backend.put(dreamToStoreRecord(d));
+        const now = await backend.count();
+        if (now > prev) newDreams.push(d);
+        prev = now;
+      }
+      await backend.save();
+      return prev - before;
+    });
   }
 
   if (maxTs !== undefined && maxTs !== since) {