@dzhechkov/harness-core 0.3.142 → 0.3.143

package/src/backlog.ts

@@ -76,11 +76,50 @@ export interface DedupVerdict {
   /** Top-1 raw cosine (ADR-002 — never an RRF score). `-1` when there is nothing to compare against. */
   readonly cosine: number;
   readonly matchedId: string | undefined;
+  /**
+   * The id of the TOP-1 candidate whatever band it landed in — the ADR-002 CALIBRATION surface (idea
+   * ce914ac2). `matchedId` is only set for a DUPLICATE, so a RELATED verdict used to report a cosine with
+   * no way to see WHICH idea produced it; a user calibrating the 0.92 band needs the pair, not the number.
+   * Purely observational: it never changes the verdict.
+   */
+  readonly topMatchId: string | undefined;
   readonly relatedIds: readonly string[];
   /** True when the embedder was unavailable and dedup degraded to exact-text (ADR-002 §degrade). */
   readonly exactTextOnly: boolean;
 }
 
+/* ── Effort parsing (idea 86096d6d): a clamp the user cannot see is a silent surprise. ── */
+
+/** The result of interpreting a `--effort` argument, with the note the CLI must ECHO when it altered it. */
+export interface EffortParse {
+  readonly effort: number;
+  /** True when the parsed value was altered (clamped, floored, or rejected) — the CLI prints `note`. */
+  readonly adjusted: boolean;
+  /** Human line, e.g. `effort 13 → clamped to 5 (scale 1-5)`. Present iff `adjusted`. */
+  readonly note?: string;
+}
+
+export const EFFORT_MIN = 1;
+export const EFFORT_MAX = 5;
+
+/**
+ * PURE `--effort` interpreter. `dz backlog add --effort 13` used to store 5 and say NOTHING, so the user
+ * kept a wrong mental model of the scale (idea 86096d6d). Every alteration now carries a printable note;
+ * an in-range integer is returned untouched with `adjusted:false` (no noise on the happy path).
+ */
+export function parseEffort(raw: string | undefined, fallback: number): EffortParse {
+  if (raw === undefined) return { effort: fallback, adjusted: false };
+  const v = Number(raw);
+  if (!Number.isFinite(v)) {
+    return { effort: fallback, adjusted: true, note: `effort ${JSON.stringify(raw)} → not a number, using ${fallback} (scale ${EFFORT_MIN}-${EFFORT_MAX})` };
+  }
+  if (v < EFFORT_MIN) return { effort: EFFORT_MIN, adjusted: true, note: `effort ${raw} → clamped to ${EFFORT_MIN} (scale ${EFFORT_MIN}-${EFFORT_MAX})` };
+  if (v > EFFORT_MAX) return { effort: EFFORT_MAX, adjusted: true, note: `effort ${raw} → clamped to ${EFFORT_MAX} (scale ${EFFORT_MIN}-${EFFORT_MAX})` };
+  const floored = Math.floor(v);
+  if (floored !== v) return { effort: floored, adjusted: true, note: `effort ${raw} → rounded down to ${floored} (scale ${EFFORT_MIN}-${EFFORT_MAX}, whole numbers)` };
+  return { effort: floored, adjusted: false };
+}
+
 /* ================================================================== */
 /*  CONFIG (readBacklogConfig) — defensive, Number.isFinite clamps.     */
 /* ================================================================== */
@@ -257,6 +296,117 @@ export function writeIdeas(projectRoot: string, ideas: readonly IdeaRecord[]): v
   renameSync(tmp, path);
 }
 
+/* ── Store privacy (idea ec4cd60d): raw ideas are prompt-class PRIVATE content, like recall-usage.jsonl. ── */
+
+export type GitignoreAction = 'created' | 'appended' | 'already-covered' | 'user-opted-out' | 'skipped';
+export interface GitignoreScaffold {
+  readonly action: GitignoreAction;
+  readonly path: string;
+  /** Set for `skipped` (the I/O reason) and `user-opted-out` (the negation line we obeyed). */
+  readonly reason?: string;
+}
+
+/** The entry + its one-line rationale, written verbatim so the file explains itself. */
+const BACKLOG_IGNORE_ENTRY = '.dz/backlog/';
+const BACKLOG_IGNORE_COMMENT = '# dz backlog — captured ideas are private prompt-class content';
+
+/**
+ * Normalise ONE .gitignore pattern to the bare path it targets, so the equally-valid spellings of the
+ * same rule compare equal: a leading `/` (repo-root anchor), a trailing `/**` or `/*` (recursive glob),
+ * and a trailing `/` (directory marker) are all decoration around the same path. Returns `undefined`
+ * for anything that is not a plain path pattern (a comment, an empty line, or a pattern carrying a
+ * wildcard we do NOT interpret) — an uninterpretable pattern must never be read as coverage.
+ */
+function normaliseIgnorePattern(body: string): string | undefined {
+  let p = body.trim();
+  if (p === '' || p.startsWith('#')) return undefined;
+  if (p.startsWith('/')) p = p.slice(1); // repo-root anchor: `/.dz/` ≡ `.dz/`
+  p = p.replace(/\/\*\*$/, '').replace(/\/\*$/, ''); // `.dz/**` / `.dz/*` ≡ `.dz`
+  p = p.replace(/\/+$/, ''); // trailing directory marker
+  if (p === '' || p.includes('*') || p.includes('?') || p.includes('[')) return undefined; // not a plain path
+  return p;
+}
+
+/** True when the pattern targets the backlog store (directly or via its `.dz` parent). */
+function targetsBacklogStore(pattern: string): boolean {
+  return pattern === '.dz' || pattern === '.dz/backlog';
+}
+
+export type BacklogIgnoreStatus = 'covered' | 'negated' | 'uncovered';
+
+/**
+ * PURE .gitignore verdict for the backlog store. Deliberately NOT a full gitignore engine — it
+ * recognises the plain-path spellings of the rule (`/.dz/`, `.dz/**`, `.dz/backlog`, …) and refuses to
+ * interpret anything else, because a wrong-but-clever matcher either double-appends or silently
+ * decides a store is private when it is not.
+ *
+ * `negated` wins over `covered`: a `!.dz/backlog/` line (anchored or not) is the user saying *"track
+ * this on purpose"*. We obey it — appending a rule that overrides the user's explicit opt-out would be
+ * this tool deciding it knows better.
+ */
+export function backlogIgnoreStatus(gitignoreText: string): BacklogIgnoreStatus {
+  let covered = false;
+  for (const raw of String(gitignoreText).split('\n')) {
+    const line = raw.trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const negated = line.startsWith('!');
+    const pattern = normaliseIgnorePattern(negated ? line.slice(1) : line);
+    if (pattern === undefined || !targetsBacklogStore(pattern)) continue;
+    if (negated) return 'negated'; // explicit user intent — decided, no further scanning
+    covered = true;
+  }
+  return covered ? 'covered' : 'uncovered';
+}
+
+/** Back-compat shim: "is it ignored?" — a negation is NOT coverage (the store is tracked on purpose). */
+export function backlogIgnoreCovered(gitignoreText: string): boolean {
+  return backlogIgnoreStatus(gitignoreText) === 'covered';
+}
+
+/** The file's dominant line ending, so an append does not mix CRLF and LF in one file. */
+function dominantEol(text: string): '\r\n' | '\n' {
+  const crlf = (text.match(/\r\n/g) ?? []).length;
+  const lf = (text.match(/\n/g) ?? []).length - crlf;
+  return crlf > lf ? '\r\n' : '\n';
+}
+
+/** Atomic write (tmp + rename in the SAME dir) — the ideas.jsonl discipline: a crash never truncates. */
+function writeFileAtomic(path: string, body: string): void {
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, body);
+  renameSync(tmp, path);
+}
+
+/**
+ * Ensure the backlog store is gitignored, at the moment the feature FIRST creates it (idea ec4cd60d).
+ * Creates a `.gitignore` when there is none; appends the entry (+ its comment) when the project has one
+ * that does not cover the store; touches NOTHING when it is already covered OR when the user explicitly
+ * negated the rule. The write is ATOMIC and preserves the file's dominant EOL.
+ * Never throws — an unwritable .gitignore degrades to `skipped`, and the CALLER must say so out loud
+ * (a silently un-ignored store is exactly the privacy leak this function exists to prevent).
+ */
+export function ensureBacklogGitignored(projectRoot: string): GitignoreScaffold {
+  const path = join(projectRoot, '.gitignore');
+  try {
+    if (!existsSync(path)) {
+      writeFileAtomic(path, `${BACKLOG_IGNORE_COMMENT}\n${BACKLOG_IGNORE_ENTRY}\n`);
+      return { action: 'created', path };
+    }
+    const text = readFileSync(path, 'utf-8');
+    const status = backlogIgnoreStatus(text);
+    if (status === 'covered') return { action: 'already-covered', path };
+    if (status === 'negated') {
+      return { action: 'user-opted-out', path, reason: 'a "!" negation for the backlog store is present — respecting the explicit opt-out and adding nothing' };
+    }
+    const eol = dominantEol(text);
+    const sep = text === '' || text.endsWith('\n') ? '' : eol;
+    writeFileAtomic(path, `${text}${sep}${eol}${BACKLOG_IGNORE_COMMENT}${eol}${BACKLOG_IGNORE_ENTRY}${eol}`);
+    return { action: 'appended', path };
+  } catch (err) {
+    return { action: 'skipped', path, reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
 /** Pre-mutation snapshot (NFR-6) — mirrors `snapshotStore`. A failed snapshot returns `{error}` so
  *  the caller ABORTS the mutation (no partial merge). */
 export interface SnapshotResult {
@@ -303,15 +453,15 @@ export function classifyDedup(
   const sorted = candidates.filter((c) => Number.isFinite(c.cosine)).sort((a, b) => b.cosine - a.cosine);
   const top = sorted[0];
   const exactTextOnly = opts.exactTextOnly === true;
-  if (top === undefined) return { action: 'new', cosine: -1, matchedId: undefined, relatedIds: [], exactTextOnly };
+  if (top === undefined) return { action: 'new', cosine: -1, matchedId: undefined, topMatchId: undefined, relatedIds: [], exactTextOnly };
   if (top.cosine >= cfg.duplicateThreshold) {
-    return { action: 'duplicate', cosine: top.cosine, matchedId: top.id, relatedIds: [], exactTextOnly };
+    return { action: 'duplicate', cosine: top.cosine, matchedId: top.id, topMatchId: top.id, relatedIds: [], exactTextOnly };
   }
   const related = sorted.filter((c) => c.cosine >= cfg.relatednessFloor && c.cosine < cfg.duplicateThreshold);
   if (related.length > 0) {
-    return { action: 'related', cosine: top.cosine, matchedId: undefined, relatedIds: related.map((c) => c.id), exactTextOnly };
+    return { action: 'related', cosine: top.cosine, matchedId: undefined, topMatchId: top.id, relatedIds: related.map((c) => c.id), exactTextOnly };
   }
-  return { action: 'new', cosine: top.cosine, matchedId: undefined, relatedIds: [], exactTextOnly };
+  return { action: 'new', cosine: top.cosine, matchedId: undefined, topMatchId: top.id, relatedIds: [], exactTextOnly };
 }
 
 /** Injectable deps so the production dedup path is testable without a live agentdb. */
@@ -354,8 +504,8 @@ export async function dedupIdea(projectRoot: string, text: string, cfg: BacklogC
     // EXACT-text safety net: identical text among existing ideas is still a DUPLICATE (content-addressed
     // idempotency, ADR-002 §degrade). Otherwise NEW — the RELATED band needs cosine and is skipped.
     const match = ideas.find((i) => i.text === text);
-    if (match !== undefined) return { action: 'duplicate', cosine: 1, matchedId: match.id, relatedIds: [], exactTextOnly: true };
-    return { action: 'new', cosine: -1, matchedId: undefined, relatedIds: [], exactTextOnly: result.error !== undefined };
+    if (match !== undefined) return { action: 'duplicate', cosine: 1, matchedId: match.id, topMatchId: match.id, relatedIds: [], exactTextOnly: true };
+    return { action: 'new', cosine: -1, matchedId: undefined, topMatchId: undefined, relatedIds: [], exactTextOnly: result.error !== undefined };
   }
   return classifyDedup(candidates, cfg.dedup);
 }
@@ -364,30 +514,135 @@ export async function dedupIdea(projectRoot: string, text: string, cfg: BacklogC
 /*  ALIGNMENT (AM-3 / ADR-003) — weighted-MAX cosine over the GoalMap.  */
 /* ================================================================== */
 
-/** Defensive GoalMap reader — never throws; a missing/corrupt file ⇒ empty compass. */
-export function readGoalMap(projectRoot: string): GoalMap {
+/** One goal entry the reader REFUSED, with the reason — the anti-vacuous-valid evidence (idea 960c9f26). */
+export interface DroppedGoal {
+  /** 0-based index of the entry in the file's `goals` array. */
+  readonly index: number;
+  /** Machine-stable reason, e.g. `missing "statement"`. */
+  readonly reason: string;
+}
+
+/**
+ * What the defensive read actually SAW. `readGoalMap` throws away the drops (correct for runtime paths —
+ * a corrupt compass must never break capture), but `goals --validate` needs them: a goals.json whose every
+ * entry was silently dropped previously reported *"valid (0 goal(s))"* — a vacuous pass that hid the user's
+ * typo (`text` instead of `statement`). This variant is the validate-facing reader.
+ */
+export interface GoalMapRead {
+  readonly goalMap: GoalMap;
+  /** Entries present in the file's `goals` array (kept + dropped). */
+  readonly present: number;
+  readonly dropped: readonly DroppedGoal[];
+  /**
+   * Fields the reader REPAIRED to keep the runtime safe. The clamp happens BEFORE any validation could
+   * see the original, so a `weight: 7` becomes a legal 1 and the validator's out-of-range branch is
+   * unreachable — a silent repair reported as "valid". These carry the RAW value so `goals --validate`
+   * can warn about what the user actually wrote while the runtime keeps the clamped value.
+   */
+  readonly repaired: readonly RepairedGoalField[];
+  /** Set when the file exists but could not be parsed / has no `goals` array. */
+  readonly parseError?: string;
+}
+
+/** One field the defensive reader clamped/replaced, with both the raw and the used value. */
+export interface RepairedGoalField {
+  readonly index: number;
+  readonly id: string;
+  readonly field: 'weight';
+  readonly raw: unknown;
+  readonly used: number;
+  /** Human reason, e.g. `weight 7 is out of (0,1]`. */
+  readonly reason: string;
+}
+
+/** Reason an entry cannot become a Goal — `undefined` when it is well-formed. */
+function goalDropReason(o: unknown): string | undefined {
+  if (o === null || typeof o !== 'object' || Array.isArray(o)) return 'not an object';
+  const r = o as Record<string, unknown>;
+  if (typeof r.id !== 'string') return 'missing "id"';
+  if (typeof r.statement !== 'string') return 'missing "statement"';
+  return undefined;
+}
+
+/**
+ * Detailed GoalMap read — never throws, and REPORTS what it dropped (idea 960c9f26). `readGoalMap` is the
+ * lossy runtime view of this; both share one parser so they can never disagree about what a goal is.
+ */
+export function readGoalMapDetailed(projectRoot: string): GoalMapRead {
   const path = goalsPath(projectRoot);
-  if (!existsSync(path)) return { version: 1, goals: [] };
+  if (!existsSync(path)) return { goalMap: { version: 1, goals: [] }, present: 0, dropped: [], repaired: [] };
+  let parsed: { version?: unknown; goals?: unknown };
   try {
-    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { version?: unknown; goals?: unknown };
-    const goals: Goal[] = Array.isArray(parsed.goals)
-      ? parsed.goals
-          .map((g): Goal | undefined => {
-            const o = g as Record<string, unknown>;
-            if (typeof o.id !== 'string' || typeof o.statement !== 'string') return undefined;
-            return {
-              id: o.id,
-              statement: o.statement,
-              weight: clampNum(o.weight, Number.MIN_VALUE, 1, 1),
-              keywords: Array.isArray(o.keywords) ? o.keywords.filter((k): k is string => typeof k === 'string') : [],
-            };
-          })
-          .filter((g): g is Goal => g !== undefined)
-      : [];
-    return { version: typeof parsed.version === 'number' ? parsed.version : 1, goals };
-  } catch {
-    return { version: 1, goals: [] };
+    parsed = JSON.parse(readFileSync(path, 'utf-8')) as { version?: unknown; goals?: unknown };
+  } catch (err) {
+    return {
+      goalMap: { version: 1, goals: [] },
+      present: 0,
+      dropped: [],
+      repaired: [],
+      parseError: `goals.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+  // Valid JSON that is not an object (null, a number, an array) must not crash the never-throw
+  // reader: `parsed.version` on null is a TypeError (Codex re-QE HIGH).
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {
+      goalMap: { version: 1, goals: [] },
+      present: 0,
+      dropped: [],
+      repaired: [],
+      parseError: 'goals.json is valid JSON but not an object',
+    };
   }
+  const version = typeof parsed.version === 'number' ? parsed.version : 1;
+  if (!Array.isArray(parsed.goals)) {
+    return {
+      goalMap: { version, goals: [] },
+      present: 0,
+      dropped: [],
+      repaired: [],
+      parseError: 'goals.json has no `goals` array',
+    };
+  }
+  const goals: Goal[] = [];
+  const dropped: DroppedGoal[] = [];
+  const repaired: RepairedGoalField[] = [];
+  parsed.goals.forEach((g, index) => {
+    const reason = goalDropReason(g);
+    if (reason !== undefined) {
+      dropped.push({ index, reason });
+      return;
+    }
+    const o = g as Record<string, unknown>;
+    const id = o.id as string;
+    // The clamp keeps the RUNTIME safe; the raw value is recorded so validation can still see what the
+    // user wrote (MED-7: clamping before validating made the validator's out-of-range branch dead code).
+    const weight = clampNum(o.weight, Number.MIN_VALUE, 1, 1);
+    if (o.weight !== undefined && o.weight !== weight) {
+      repaired.push({
+        index,
+        id,
+        field: 'weight',
+        raw: o.weight,
+        used: weight,
+        reason: typeof o.weight === 'number' && Number.isFinite(o.weight)
+          ? `weight ${o.weight} is out of (0,1]`
+          : `weight ${JSON.stringify(o.weight) ?? String(o.weight)} is not a number in (0,1]`,
+      });
+    }
+    goals.push({
+      id,
+      statement: o.statement as string,
+      weight,
+      keywords: Array.isArray(o.keywords) ? o.keywords.filter((k): k is string => typeof k === 'string') : [],
+    });
+  });
+  return { goalMap: { version, goals }, present: parsed.goals.length, dropped, repaired };
+}
+
+/** Defensive GoalMap reader — never throws; a missing/corrupt file ⇒ empty compass (the runtime path). */
+export function readGoalMap(projectRoot: string): GoalMap {
+  return readGoalMapDetailed(projectRoot).goalMap;
 }
 
 /** The text embedded for a goal: statement + keywords (same convention across cache + score). */

package/src/guard.ts

@@ -56,6 +56,110 @@ export interface GuardFacts {
   readonly skillPacks?: readonly { readonly name: string; readonly nonRegistrable: readonly string[] }[];
   /** for readme-first: per publishable package, is a version bump staged without a README change? */
   readonly readmeFirst?: readonly { readonly name: string; readonly versionBumped: boolean; readonly readmeChanged: boolean }[];
+  /**
+   * for lockfile-in-sync: what each workspace package DECLARES vs what pnpm-lock.yaml RECORDS for that
+   * importer. `parsed:false` (or the fact absent) ⇒ the rule reports nothing — fail-open by construction,
+   * because a lockfile we could not read is not evidence of a defect.
+   */
+  readonly lockfile?: {
+    readonly parsed: boolean;
+    readonly importers?: readonly {
+      /** importer path as pnpm keys it, e.g. `packages/@dzhechkov/harness-cli`. */
+      readonly importer: string;
+      /** the `@dzhechkov/*` specs the package.json declares (deps + devDeps). */
+      readonly declared: Readonly<Record<string, string>>;
+      /** the specs pnpm-lock.yaml records for this importer; `undefined` ⇒ the importer is absent. */
+      readonly locked?: Readonly<Record<string, string>> | undefined;
+    }[];
+  };
+}
+
+/** The lowest `lockfileVersion` whose importers carry the `specifier:`/`version:` pair this parser reads. */
+export const MIN_RECOGNISED_LOCKFILE_VERSION = 9;
+
+/**
+ * RECOGNISE-OR-REFUSE `pnpm-lock.yaml` importers parser — PURE, no YAML dependency. Reads exactly one
+ * shape: `importers:` → `<path>:` → `<section>:` → `'<dep>':` → `specifier: <value>` (lockfileVersion 9+).
+ *
+ * "Tolerant" must mean *refuses to guess*, NOT *guesses quietly*. A half-parse is the dangerous outcome:
+ * a lockfileVersion-6 file lists deps as `dep: version` one-liners under a separate `specifiers:` map, so
+ * a lenient reader finds the importer KEYS, records ZERO specifiers, and the rule then reports every real
+ * dependency as *"not recorded in pnpm-lock.yaml"* — a false-positive storm dressed up as fail-open. So we
+ * return `undefined` (⇒ the rule reports NOTHING) unless every one of these holds:
+ *   1. `lockfileVersion` is present and ≥ {@link MIN_RECOGNISED_LOCKFILE_VERSION};
+ *   2. an `importers:` section exists and yields at least one importer;
+ *   3. no legacy inline `dep: value` line appears at dependency depth (the v5/v6 shape);
+ *   4. at least one `specifier:` was read, and NO importer came out empty (a truncated file, or a shape
+ *      we do not understand, always trips this).
+ *
+ * `dependencies` and `devDependencies` are merged: a dep appears in only one of them per importer, and
+ * the rule compares specifier strings only.
+ */
+export function parsePnpmLockImporters(lockText: unknown): Record<string, Record<string, string>> | undefined {
+  if (typeof lockText !== 'string' || lockText === '') return undefined;
+
+  // (1) version gate — the ONLY layout this parser claims to understand.
+  const versionLine = lockText.match(/^lockfileVersion:\s*['"]?([0-9]+(?:\.[0-9]+)?)['"]?\s*$/m);
+  const version = versionLine?.[1] !== undefined ? Number.parseFloat(versionLine[1]) : Number.NaN;
+  if (!Number.isFinite(version) || version < MIN_RECOGNISED_LOCKFILE_VERSION) return undefined;
+
+  const importers: Record<string, Record<string, string>> = {};
+  let inImporters = false;
+  let current: string | undefined;
+  let currentDep: string | undefined;
+  let specifiersSeen = 0;
+  let sawImportersKey = false;
+  for (const line of lockText.split('\n')) {
+    if (/^importers:\s*$/.test(line)) {
+      inImporters = true;
+      sawImportersKey = true;
+      continue;
+    }
+    if (!inImporters) continue;
+    if (/^\S/.test(line)) break; // a new top-level key ends the importers section
+    if (line.trim() === '') continue;
+    const importer = line.match(/^ {2}(\S.*?):\s*$/);
+    if (importer && importer[1] !== undefined) {
+      current = unquoteYaml(importer[1]);
+      importers[current] = importers[current] ?? {};
+      currentDep = undefined;
+      continue;
+    }
+    if (current === undefined) continue;
+    // (3) a dependency-depth line that carries an INLINE value is the pre-v9 shape → refuse outright
+    // rather than silently recording nothing for this importer.
+    if (/^ {6}\S.*?:\s+\S/.test(line)) return undefined;
+    const dep = line.match(/^ {6}(\S.*?):\s*$/);
+    if (dep && dep[1] !== undefined) {
+      // A dep line while the PREVIOUS dep never got its specifier = a truncated/unrecognized shape —
+      // refuse the whole parse rather than warn on a half-read (Codex re-QE: pending currentDep).
+      if (currentDep !== undefined) return undefined;
+      currentDep = unquoteYaml(dep[1]);
+      continue;
+    }
+    const spec = line.match(/^ {8}specifier:\s*(.+?)\s*$/);
+    if (spec && spec[1] !== undefined && currentDep !== undefined) {
+      importers[current]![currentDep] = unquoteYaml(spec[1]);
+      specifiersSeen += 1;
+      currentDep = undefined;
+    }
+  }
+  // EOF with a dep still awaiting its specifier: truncated — refuse, never warn on a half-parse.
+  if (currentDep !== undefined) return undefined;
+
+  // (2) + (4) structural confidence: no importers, no specifiers, or ANY importer that came out empty
+  // (truncation, an unread section shape) means we did not really parse this file — report nothing.
+  if (!sawImportersKey || Object.keys(importers).length === 0 || specifiersSeen === 0) return undefined;
+  for (const deps of Object.values(importers)) if (Object.keys(deps).length === 0) return undefined;
+  return importers;
+}
+
+function unquoteYaml(s: string): string {
+  const t = s.trim();
+  if ((t.startsWith("'") && t.endsWith("'") && t.length >= 2) || (t.startsWith('"') && t.endsWith('"') && t.length >= 2)) {
+    return t.slice(1, -1);
+  }
+  return t;
 }
 
 /** The built-in rule set (works with no config). Ops are the mutating operations each rule guards. */
@@ -66,6 +170,7 @@ export const DEFAULT_RULES: readonly GuardRule[] = [
   { id: 'readme-consistency', severity: 'soft', ops: ['publish'], description: 'README counts agree (CJM header vs All Commands, etc.)' },
   { id: 'skills-registrable', severity: 'soft', ops: ['publish'], description: 'every skill directory in a skill pack has a depth-1 SKILL.md (a buried or missing one ships un-registrable — the health-advisor 1.2.0 class)' },
   { id: 'readme-first', severity: 'soft', ops: ['publish'], description: 'a package with a staged version bump must update its own README.md in the same change (README-first)' },
+  { id: 'lockfile-in-sync', severity: 'soft', ops: ['publish'], description: 'every workspace @dzhechkov/* dependency spec matches the specifier pnpm-lock.yaml records for that importer (a dep bump without a lockfile refresh breaks CI with ERR_PNPM_OUTDATED_LOCKFILE). SOFT-ONLY — a config cannot promote it to HARD' },
   { id: 'store-bloat-cap', severity: 'soft', ops: ['teach', 'consolidate'], description: 'the learned store is within its size cap' },
 ];
 
@@ -154,6 +259,40 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
     }
     return out;
   },
+  'lockfile-in-sync': (f, _sev) => {
+    // The 2026-07-28 CI break, mechanized: an overnight dep bump edited package.json and left
+    // pnpm-lock.yaml stale, so `pnpm install --frozen-lockfile` died with ERR_PNPM_OUTDATED_LOCKFILE.
+    // SOFT + FAIL-OPEN: no lockfile evidence ⇒ NO violation. A guard that cannot read the lockfile must
+    // never invent one — a false block on publish costs more than the miss it prevents.
+    // The injected severity is IGNORED on purpose (MED-6): this rule emits `soft` unconditionally, so
+    // neither a config promotion nor a hand-built rules array can turn a tolerant parser into a blocker.
+    const sev: GuardSeverity = 'soft';
+    const lock = f.lockfile;
+    if (!lock || typeof lock !== 'object' || lock.parsed !== true || !Array.isArray(lock.importers)) return [];
+    const out: Violation[] = [];
+    for (const imp of lock.importers) {
+      if (!imp || typeof imp.importer !== 'string' || !imp.declared || typeof imp.declared !== 'object') continue;
+      const declared = Object.entries(imp.declared).filter(([dep, spec]) => dep.startsWith('@dzhechkov/') && typeof spec === 'string');
+      if (declared.length === 0) continue;
+      if (imp.locked === undefined || imp.locked === null) {
+        out.push({
+          rule: 'lockfile-in-sync',
+          severity: sev,
+          detail: `${imp.importer}: declares ${declared.length} @dzhechkov/* dep(s) but has no importer entry in pnpm-lock.yaml — run \`pnpm install\` (CI installs with --frozen-lockfile)`,
+        });
+        continue;
+      }
+      for (const [dep, spec] of declared) {
+        const locked = imp.locked[dep];
+        if (locked === undefined) {
+          out.push({ rule: 'lockfile-in-sync', severity: sev, detail: `${imp.importer}: ${dep} = "${spec}" is not recorded in pnpm-lock.yaml — run \`pnpm install\` (CI installs with --frozen-lockfile)` });
+        } else if (locked !== spec) {
+          out.push({ rule: 'lockfile-in-sync', severity: sev, detail: `${imp.importer}: ${dep} = "${spec}" in package.json but "${locked}" in pnpm-lock.yaml — run \`pnpm install\` to refresh the lockfile (CI installs with --frozen-lockfile)` });
+        }
+      }
+    }
+    return out;
+  },
   'store-bloat-cap': (f, sev) => {
     const s = f.store;
     if (!s || !Number.isFinite(s.count) || !Number.isFinite(s.cap) || s.cap <= 0) return [];
@@ -161,6 +300,14 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
   },
 };
 
+/**
+ * Rules that may NEVER be promoted to HARD, whatever a config says. A rule whose evidence comes from a
+ * deliberately tolerant parser must not be able to BLOCK an operation: the parser's own design admits it
+ * may not understand a file, and "I might be wrong" plus "block the publish" is the wrong pair. Disabling
+ * such a rule stays allowed — only the promotion is refused.
+ */
+export const SOFT_ONLY_RULES: readonly string[] = ['lockfile-in-sync'];
+
 /** Merge a user config over the defaults: override severity, disable (enabled:false), never add an un-checked rule. */
 export function resolveRules(userRules?: readonly Partial<GuardRule>[]): GuardRule[] {
   const byId = new Map<string, GuardRule>(DEFAULT_RULES.map((r) => [r.id, r]));
@@ -168,9 +315,12 @@ export function resolveRules(userRules?: readonly Partial<GuardRule>[]): GuardRu
     if (!u || typeof u.id !== 'string') continue;
     const base = byId.get(u.id);
     if (!base) continue; // a config rule with no built-in checker is ignored (fail-safe: no un-enforceable rules)
+    // A SOFT-ONLY rule keeps its severity even when the config asks for hard (see SOFT_ONLY_RULES).
+    const severity = u.severity === 'hard' || u.severity === 'soft' ? u.severity : undefined;
+    const allowedSeverity = severity !== undefined && !(severity === 'hard' && SOFT_ONLY_RULES.includes(u.id)) ? severity : undefined;
     byId.set(u.id, {
       ...base,
-      ...(u.severity === 'hard' || u.severity === 'soft' ? { severity: u.severity } : {}),
+      ...(allowedSeverity !== undefined ? { severity: allowedSeverity } : {}),
       ...(typeof u.enabled === 'boolean' ? { enabled: u.enabled } : {}),
     });
   }