@dzhechkov/harness-core 0.3.142 → 0.3.144

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 } : {}),
     });
   }

package/src/index.ts

@@ -327,6 +327,58 @@ export * from './skills-verify.js';
 // finding, not a pass).
 export * from './compounding.js';
 
+// Cold-vs-warm EPOCH RUNNER (feature epoch-replay, scout idea #4) — the RESULT leg to compounding's
+// readiness leg. Orchestrates + scores; never calls a model. SUPPORTED requires two DISJOINT Wilson
+// intervals; INCONCLUSIVE is a first-class honest outcome.
+// NOTE: `replayableInstances` / `ReplayInstance` are OWNED by compounding.js and merely re-exported
+// there, so this star-export must not re-export them again (duplicate-export error).
+export {
+  WILSON_Z,
+  MIN_INSTANCES,
+  FALSIFY_NO_LIFT_MIN_N,
+  NO_LIFT_MARGIN,
+  MARGIN_MAX,
+  MARGIN_MIN_EXCLUSIVE,
+  DIGEST_HONEST_SCOPE,
+  WORK_ORDER_KIND,
+  WORK_ORDER_VERSION,
+  DEFAULT_WORD_MIN,
+  DEFAULT_WORD_MAX,
+  DEFAULT_MOCK_N,
+  DEFAULT_MOCK_SEED,
+  wilsonInterval,
+  liftInterval,
+  corpusFingerprint,
+  isValidMargin,
+  workOrderDigest,
+  verifyWorkOrder,
+  buildWorkOrder,
+  buildJudgePrompts,
+  unblindJudgments,
+  scoreEpochReplay,
+  generateMockOutcomes,
+  renderEpochReplayResult,
+  renderWorkOrderSummary,
+  renderJudgePromptsSummary,
+  type WilsonInterval,
+  type LiftInterval,
+  type WorkOrder,
+  type WorkOrderItem,
+  type WorkOrderOptions,
+  type WorkOrderVerification,
+  type JudgePrompt,
+  type JudgePromptsResult,
+  type Arm,
+  type EpochOutcome,
+  type Judgment,
+  type UnblindResult,
+  type EpochVerdict,
+  type ArmResult,
+  type EpochReplayResult,
+  type ScoreOptions,
+  type MockOptions,
+} from './epoch-replay.js';
+
 // Run-process scorecard (feature dz-score, Reading C) — scores the DISCIPLINE of a feature-adr run
 // from its artifacts. Descriptive-only, permanently: it never gates.
 export * from './score.js';