@mcptoolshop/style-dataset-lab 3.2.0 → 3.4.0

package/lib/eval-pack.js

@@ -10,14 +10,13 @@
  * 4. Subject continuity — same-subject records for identity testing
  */
 
-import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { loadProjectConfig, detectLane, detectGroup } from './config.js';
 import { loadRecord } from './records.js';
-import { computeConfigFingerprint, SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
-import { inputError } from './errors.js';
+import { computeConfigFingerprint, SCHEMA_VERSION, checkManifestVersion, claimIdDir } from './snapshot.js';
 
 /**
  * Generate an eval-pack ID: eval-YYYYMMDD-HHMMSS-XXXX
@@ -73,17 +72,18 @@ export async function buildEvalPack(projectRoot, options = {}) {
   const subjectContinuity = buildSubjectContinuity(records, maxContinuity);
 
   // Write eval pack
-  const evalId = generateEvalId();
-  const evalDir = join(projectRoot, 'eval-packs', evalId);
-  // D-005: refuse to silently overwrite on ID collision.
-  if (existsSync(evalDir)) {
-    throw inputError(
-      'EVAL_PACK_ID_COLLISION',
-      `Eval pack directory already exists: ${evalDir}`,
-      'Retry to generate a fresh eval pack ID.',
-    );
-  }
-  await mkdir(evalDir, { recursive: true });
+  // SDL-M10: atomically claim the eval-pack id/dir — closes the
+  // check-then-act race the old existsSync+recursive-mkdir pattern had
+  // (D-005's intent, now actually race-proof; see claimIdDir in snapshot.js).
+  const { id: evalId, dir: evalDir } = await claimIdDir(
+    join(projectRoot, 'eval-packs'),
+    generateEvalId,
+    {
+      code: 'EVAL_PACK_ID_COLLISION',
+      message: 'Could not claim a unique eval-pack ID — every candidate collided with an existing eval-pack directory.',
+      hint: 'Retry; if this persists, another sdlab process may be creating eval packs in a tight loop.',
+    },
+  );
 
   // DB-014: compute `records_available` so the manifest reports sampled vs.
   // available. Operators can see when they're leaving records on the table.

package/lib/eval-runs.js

@@ -14,6 +14,7 @@ import { loadTrainingManifest } from './training-manifests.js';
 import { loadEvalPack } from './eval-pack.js';
 import { loadProjectConfig, detectLane, detectGroup } from './config.js';
 import { SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
+import { inputError } from './errors.js';
 
 // DB-008: cap sample record_ids per failure bucket so scorecards stay small
 // but the operator has enough detail to start investigation.
@@ -91,6 +92,18 @@ export async function scoreEvalRun(projectRoot, evalRunId, outputsPath) {
 
   // Load eval pack tasks
   const evalPackDir = join(projectRoot, 'eval-packs', runManifest.eval_pack_id);
+  // F2: createEvalRun only ever stores the eval_pack_id string — it never
+  // re-verifies at scoring time that the pack directory still exists. If
+  // the pack was deleted (or moved) between run creation and scoring, this
+  // used to fall straight through to the all-four-skip / vacuous-pass path
+  // below. Fail loudly here with the exact missing path instead.
+  if (!existsSync(evalPackDir)) {
+    throw inputError(
+      'EVAL_PACK_DIR_MISSING',
+      `Eval pack directory not found: ${evalPackDir} (eval run "${evalRunId}" references eval_pack_id "${runManifest.eval_pack_id}").`,
+      'The eval pack this run was created against may have been deleted or moved. Rebuild the eval pack, or create a fresh eval run against one that still exists.',
+    );
+  }
   const taskFiles = {
     'lane-coverage': 'lane-coverage.jsonl',
     'forbidden-drift': 'forbidden-drift.jsonl',
@@ -102,10 +115,18 @@ export async function scoreEvalRun(projectRoot, evalRunId, outputsPath) {
 
   // Score each task type
   const scores = {};
+  // F2: count task files that actually resolved. Object.values({}).every(...)
+  // on an EMPTY scores object is vacuously true in JS — with zero task files
+  // found, `scores` stays `{}` and the verdict below silently computed
+  // overall_verdict:'pass', overall_score:0.000 for a model that was never
+  // evaluated against anything. resolvedTaskFiles turns that into a named,
+  // structured failure instead of a green rubber stamp.
+  let resolvedTaskFiles = 0;
 
   for (const [taskName, fileName] of Object.entries(taskFiles)) {
     const taskPath = join(evalPackDir, fileName);
     if (!existsSync(taskPath)) continue;
+    resolvedTaskFiles++;
 
     const taskEntries = (await readFile(taskPath, 'utf-8'))
       .trim().split('\n').filter(Boolean).map(l => JSON.parse(l));
@@ -121,6 +142,18 @@ export async function scoreEvalRun(projectRoot, evalRunId, outputsPath) {
     }
   }
 
+  // F2: belt-and-suspenders — even with the directory-existence guard above,
+  // a pack directory that exists but has had every individual task file
+  // deleted out from under it must hit the same guard, not the vacuous
+  // Object.values({}).every(...) === true path.
+  if (resolvedTaskFiles === 0) {
+    throw inputError(
+      'EVAL_PACK_NO_TASK_FILES',
+      `Eval pack "${runManifest.eval_pack_id}" at ${evalPackDir} has no resolvable task files — nothing was scored for eval run "${evalRunId}".`,
+      `Expected at least one of: ${Object.values(taskFiles).join(', ')}. Verify the eval pack was built correctly and its directory was not partially deleted.`,
+    );
+  }
+
   // Compute overall verdict
   const allPassed = Object.values(scores).every(s => s.passed);
   const overallScore = Object.values(scores).reduce((sum, s) => sum + (s.score || 0), 0) /

package/lib/export.js

@@ -11,7 +11,7 @@ import { existsSync } from 'node:fs';
 import { platform } from 'node:os';
 import { createHash, randomBytes } from 'node:crypto';
 import { loadProjectConfig, loadExportProfile, detectLane, detectGroup } from './config.js';
-import { loadSnapshot, loadSnapshotIncluded, computeConfigFingerprint, SCHEMA_VERSION, checkManifestVersion } from './snapshot.js';
+import { loadSnapshot, loadSnapshotIncluded, computeConfigFingerprint, SCHEMA_VERSION, checkManifestVersion, claimIdDir } from './snapshot.js';
 import { loadSplit, loadSplitPartition } from './split.js';
 import { loadRecord } from './records.js';
 import { generateCard } from './card.js';
@@ -36,6 +36,63 @@ async function sha256File(filePath) {
   return createHash('sha256').update(data).digest('hex');
 }
 
+/**
+ * SDL-H6: validate that a record-relative asset_path does not escape
+ * projectRoot. Rejects absolute paths outright (ASSET_PATH_INVALID) and
+ * rejects any relative path that resolves outside projectRoot
+ * (ASSET_PATH_TRAVERSAL — e.g. "../../../../Users/victim/.ssh/id_rsa").
+ * Returns the resolved absolute path on success.
+ *
+ * This was previously inlined here only (D-007) and never ported to the
+ * training-package adapters, which checked only `existsSync` — a
+ * traversal path satisfies existsSync just as well as a legitimate one.
+ * lib/training-packages.js and the adapters import this so the exact same
+ * guard (same error codes) applies on every path that turns asset_path
+ * into a filesystem read.
+ */
+export function assertSafeAssetPath(assetPath, projectRoot, recordId) {
+  if (isAbsolute(assetPath)) {
+    throw inputError(
+      'ASSET_PATH_INVALID',
+      `Record "${recordId}" has absolute asset_path: ${assetPath}`,
+      'asset_path must be relative to the project root.',
+    );
+  }
+  const projectRootResolved = resolve(projectRoot);
+  const resolvedSource = resolve(projectRootResolved, assetPath);
+  if (resolvedSource !== projectRootResolved &&
+      !resolvedSource.startsWith(projectRootResolved + sep)) {
+    throw inputError(
+      'ASSET_PATH_TRAVERSAL',
+      `Record "${recordId}" asset_path escapes projectRoot: ${assetPath}`,
+      'Reject path traversal segments (e.g. "../") in asset_path.',
+    );
+  }
+  return resolvedSource;
+}
+
+/**
+ * SDL-H5: allowlist model for an id destined to become a filename or path
+ * segment (letters, digits, dot, underscore, hyphen only — no `/`, `\`,
+ * or `..`, so no traversal is expressible). Mirrors the character class
+ * lib/selections.js's SAFE_FILENAME_RE uses for approved-output filenames;
+ * that constant isn't exported and additionally requires an image
+ * extension suffix that doesn't apply to a bare record/entity id, so this
+ * is a parallel definition over the same allowlist model rather than a
+ * copy of a differently-shaped regex.
+ */
+export const SAFE_ID_RE = /^[A-Za-z0-9._-]+$/;
+
+export function assertSafeId(id, context) {
+  if (typeof id !== 'string' || !SAFE_ID_RE.test(id)) {
+    throw inputError(
+      'UNSAFE_RECORD_ID',
+      `Invalid id "${id}" in ${context}`,
+      'ids must match [A-Za-z0-9._-]+ — letters, digits, dot, underscore, hyphen only.',
+    );
+  }
+}
+
 /**
  * Build an export package.
  *
@@ -55,22 +112,12 @@ export async function buildExport(projectRoot, snapshotId, splitId, options = {}
   const included = await loadSnapshotIncluded(projectRoot, snapshotId);
   const recordsDir = join(projectRoot, 'records');
 
-  const exportId = generateExportId();
-  const exportDir = join(projectRoot, 'exports', exportId);
-
-  // D-005: existsSync guard prevents silent overwrite on ID collision
-  if (existsSync(exportDir)) {
-    throw inputError(
-      'EXPORT_ID_COLLISION',
-      `Export directory already exists: ${exportDir}`,
-      'Retry to generate a fresh export ID, or delete the existing directory if this was intentional.',
-    );
-  }
-
   // D-001: Verify fingerprint has not drifted since snapshot creation.
   // We inherit the snapshot's fingerprint in the export manifest; if a caller
   // has edited project config mid-flight we surface that loudly rather than
   // silently embedding a new fingerprint that masks reproducibility loss.
+  // (Checked BEFORE claiming an export id/dir below — no point reserving
+  // one if we're about to abort.)
   const currentFingerprint = computeConfigFingerprint(projectRoot);
   if (snapshot.config_fingerprint && currentFingerprint !== snapshot.config_fingerprint) {
     throw inputError(
@@ -80,18 +127,44 @@ export async function buildExport(projectRoot, snapshotId, splitId, options = {}
     );
   }
 
-  await mkdir(exportDir, { recursive: true });
+  // SDL-M10: atomically claim the export id/dir — closes the
+  // check-then-act race the old existsSync+recursive-mkdir pattern had
+  // (D-005's intent, now actually race-proof; see claimIdDir in snapshot.js).
+  const { id: exportId, dir: exportDir } = await claimIdDir(
+    join(projectRoot, 'exports'),
+    generateExportId,
+    {
+      code: 'EXPORT_ID_COLLISION',
+      message: 'Could not claim a unique export ID — every candidate collided with an existing export directory.',
+      hint: 'Retry; if this persists, another sdlab process may be creating exports in a tight loop.',
+    },
+  );
 
   // Build metadata + collect image paths
   const metadata = [];
   const imagePaths = [];
   const checksumEntries = [];
+  // F3: a record the (frozen, Law-1) snapshot included whose file was
+  // later deleted from records/ must never silently drop the export's
+  // record count below snapshot.counts.included. loadRecord() returns
+  // null on ENOENT (lib/records.js) — previously that null was a silent
+  // `continue` with no counter, no warning, no id recorded, so an export
+  // built from a snapshot with stale/deleted records would just quietly
+  // contain fewer rows than snapshot.counts.included promised. Accumulated
+  // across the whole loop (not fail-fast on the first) so the operator
+  // sees every missing id in one error instead of fixing them one at a
+  // time; hard-failed below rather than warned — see the comment at the
+  // throw site for why export specifically earns that escalation.
+  const missingRecords = [];
 
   const projectRootResolved = resolve(projectRoot);
 
   for (const entry of included) {
     const record = await loadRecord(recordsDir, entry.record_id);
-    if (!record) continue;
+    if (!record) {
+      missingRecords.push({ record_id: entry.record_id, stage: 'export' });
+      continue;
+    }
 
     const prompt = record.provenance?.prompt || '';
     const lane = detectLane(record.id, prompt, config.lanes);
@@ -115,28 +188,20 @@ export async function buildExport(projectRoot, snapshotId, splitId, options = {}
 
     // Track image for linking
     if (profile.include_images && record.asset_path) {
-      // D-007: validate asset_path does not escape projectRoot, use
-      // platform-safe basename, and name output files by record.id
-      // (D-009) to avoid collisions on shared basenames.
-      if (isAbsolute(record.asset_path)) {
-        throw inputError(
-          'ASSET_PATH_INVALID',
-          `Record "${record.id}" has absolute asset_path: ${record.asset_path}`,
-          'asset_path must be relative to the project root.',
-        );
-      }
-      const resolvedSource = resolve(projectRootResolved, record.asset_path);
-      if (resolvedSource !== projectRootResolved &&
-          !resolvedSource.startsWith(projectRootResolved + sep)) {
-        throw inputError(
-          'ASSET_PATH_TRAVERSAL',
-          `Record "${record.id}" asset_path escapes projectRoot: ${record.asset_path}`,
-          'Reject path traversal segments (e.g. "../") in asset_path.',
-        );
-      }
+      // D-007 / SDL-H6: validate asset_path does not escape projectRoot.
+      const resolvedSource = assertSafeAssetPath(record.asset_path, projectRootResolved, record.id);
       const sourceBasename = basename(record.asset_path);
       const extMatch = sourceBasename.match(/\.[^.]+$/);
       const ext = extMatch ? extMatch[0] : '';
+      // SDL-H5: the block above only validated the SOURCE asset_path —
+      // record.id becomes part of the DESTINATION filename below and was
+      // completely unvalidated despite the variable being named
+      // "safeFilename". A record id of "../../../evil" would escape the
+      // export dir on write. Reachable without hand-authoring: reingest
+      // derives ids from generated-output filenames.
+      assertSafeId(record.id, `record.id for export image filename (record "${record.id}")`);
+      // D-009: name output files by record.id to avoid collisions on
+      // shared basenames.
       const safeFilename = `${record.id}${ext}`;
       imagePaths.push({
         record_id: record.id,
@@ -146,6 +211,29 @@ export async function buildExport(projectRoot, snapshotId, splitId, options = {}
     }
   }
 
+  // F3: hard-fail on any record the snapshot promised but records/ no
+  // longer has. Nothing has been written to exportDir yet (metadata.jsonl,
+  // images/, manifest.json, etc. are all written below this point) — an
+  // aborted export leaves only the empty claimed directory behind, no
+  // partial/misleading artifacts. Export (and training-packages.js one
+  // layer further downstream) is where Law 4 ("exports are reproducible —
+  // rebuildable from snapshot + split + profile") makes completeness an
+  // actual contract rather than a courtesy, which is why this escalates to
+  // a thrown error instead of the warn()-and-continue ledger pattern used
+  // in split.js and implementation-packs.js, where the artifact produced
+  // is not itself the reproducibility-guaranteeing one.
+  if (missingRecords.length > 0) {
+    const sample = missingRecords.slice(0, 10).map(m => m.record_id);
+    throw inputError(
+      'EXPORT_MISSING_RECORDS',
+      `${missingRecords.length} of ${included.length} record(s) referenced by snapshot "${snapshotId}" could not be loaded from ${recordsDir} — this export would silently contain fewer records than the snapshot's included count.` +
+      (missingRecords.length > 10
+        ? ` First 10: ${sample.join(', ')}, ...`
+        : ` Missing: ${sample.join(', ')}.`),
+      'Record file(s) were likely deleted after the snapshot was created (a snapshot freezes the SELECTION, not the underlying record files). Restore the missing file(s), or create a fresh snapshot that reflects current on-disk records before exporting.',
+    );
+  }
+
   // Write metadata.jsonl
   const metadataPath = join(exportDir, 'metadata.jsonl');
   await writeFile(metadataPath, metadata.map(r => JSON.stringify(r)).join('\n') + '\n');

package/lib/freeze-gate.js

@@ -24,8 +24,43 @@ import { existsSync } from 'node:fs';
 import { loadBuildConfig } from './canon-build/load-config.js';
 import { loadCanonEntriesInDir, entryId } from './canon-build/load-entry.js';
 import { readFreezeStatus } from './freeze-stamp.js';
-import { appendEvent } from './freeze-events.js';
+import { appendEvent, readEventsFor } from './freeze-events.js';
 import { inputError } from './errors.js';
+import { warn } from './log.js';
+
+/**
+ * Best-effort freeze date for an entry: the `at` of its most recent freeze /
+ * override event. Returns null when the log is absent/unreadable (the freeze
+ * block itself carries no timestamp). Used only to enrich the contrastive
+ * refuse message — never load-bearing for the gate decision.
+ */
+async function latestFreezeAt(projectRoot, id) {
+  try {
+    const events = await readEventsFor(projectRoot, id);
+    for (let i = events.length - 1; i >= 0; i--) {
+      if (events[i].type === 'freeze' || events[i].type === 'override') return events[i].at;
+    }
+  } catch { /* no log / unreadable → no date */ }
+  return null;
+}
+
+/**
+ * Contrastive lead (Horvitz CHI 1999): state the DEFAULT action and the system's
+ * reasoning — who froze it, when, and why — before the override path. This is the
+ * "you probably expected to just regenerate; I'm refusing, here's why" framing.
+ */
+function contrastiveLead(id, status, freeze, frozenAt) {
+  const by = freeze?.frozen_by || 'unknown';
+  const reason = freeze?.frozen_reason || '(no reason recorded)';
+  const when = frozenAt ? ` on ${String(frozenAt).slice(0, 10)}` : '';
+  return `Default: REFUSE — "${id}" is ${status} frozen by ${by}${when}, reason: "${reason}".`;
+}
+
+/** Render the watched-field list for the contrastive override condition. */
+function watchList(freeze) {
+  const w = freeze?.watch_fields || [];
+  return w.length ? `[${w.join(', ')}]` : '[no watched fields]';
+}
 
 /**
  * Load every canon entry in a project, keyed by schema.
@@ -40,9 +75,18 @@ export async function loadAllCanonEntries(projectRoot) {
   let config;
   try {
     config = await loadBuildConfig(configPath, projectRoot);
-  } catch {
-    // Invalid config → degrade to "no gate" rather than blocking every write.
-    // The operator will hit the config error on `sdlab canon build`.
+  } catch (err) {
+    // Invalid config → degrade to "no gate" rather than blocking every write
+    // (a config typo shouldn't turn into "no one can generate/curate/paint
+    // anything in this project"). But that degrade-open MUST be audible —
+    // silently disabling freeze protection project-wide with zero operator
+    // signal is its own defect. Warn loudly to stderr; the operator will
+    // also hit the same config error surfaced properly on `sdlab canon build`.
+    warn(
+      `freeze gate disabled for this project: canon-build/config.json is invalid ` +
+        `(${err.message}). Every entry is being treated as not canon-bound — freeze/soft-advisory ` +
+        `protection is OFF until the config is fixed. Run "sdlab canon build" to see the full error.`,
+    );
     return [];
   }
   const entries = [];
@@ -109,27 +153,36 @@ export async function assertNotFrozen({
   const status = readFreezeStatus(fm);
   const id = entryId(resolved.entry);
 
-  if (status === 'frozen') {
-    throw inputError(
-      'CANON_ENTRY_FROZEN',
-      `Canon entry "${id}" is frozen; "${action}" refuses to proceed.`,
-      `Unfreeze with: sdlab canon unfreeze ${id} --reason "<why>". The override will be appended to canon-build/freeze-events.jsonl as an audit record.`,
-    );
-  }
+  // Contrastive refuse messaging (Horvitz CHI 1999): lead with the default
+  // action + the system's reasoning (who/when/why) pulled from the freeze
+  // stamp, then state the override path and its condition (don't touch the
+  // watched fields). frozenAt is best-effort from the event log.
+  if (status === 'frozen' || status === 'soft-advisory') {
+    const frozenAt = await latestFreezeAt(projectRoot, id);
+    const lead = contrastiveLead(id, status, fm.freeze, frozenAt);
+    const watched = watchList(fm.freeze);
+
+    if (status === 'frozen') {
+      throw inputError(
+        'CANON_ENTRY_FROZEN',
+        `${lead} A hard freeze has no inline bypass, so "${action}" will not proceed.`,
+        `Unfreeze with: sdlab canon unfreeze ${id} --reason "<why>" (appended to canon-build/freeze-events.jsonl as an audit record). This freeze watches ${watched}.`,
+      );
+    }
 
-  if (status === 'soft-advisory') {
+    // soft-advisory
     if (!allowSoftAdvisoryBypass) {
       throw inputError(
         'CANON_ENTRY_FROZEN',
-        `Canon entry "${id}" is soft-advisory frozen; "${action}" refuses to proceed.`,
-        `This command does not support a --i-know bypass. Run "sdlab canon unfreeze ${id} --reason \\"<why>\\"" for a proper unfreeze, or pick a command that accepts --i-know.`,
+        `${lead} "${action}" has no --i-know bypass.`,
+        `Run: sdlab canon unfreeze ${id} --reason "<why>" for a proper unfreeze, or pick a command that accepts --i-know. Watched fields: ${watched}.`,
       );
     }
     if (!bypassReason) {
       throw inputError(
         'CANON_ENTRY_FROZEN',
-        `Canon entry "${id}" is soft-advisory frozen; "${action}" requires --i-know AND --reason to bypass.`,
-        `Re-run with: --i-know --reason "<short reason>". The bypass will be logged to canon-build/freeze-events.jsonl.`,
+        `${lead} Override requires --i-know AND --reason.`,
+        `Re-run with --i-know --reason "<why>" ONLY if your change does not touch the watched fields ${watched}. The bypass is logged to canon-build/freeze-events.jsonl.`,
       );
     }
     // Bypass allowed — log and proceed.

package/lib/freeze-stamp.js

@@ -10,6 +10,7 @@
 
 import { createHash } from 'node:crypto';
 import { getByPath } from './canon-build/load-config.js';
+import { inputError } from './errors.js';
 
 /**
  * The four legal freeze statuses. Entries without a `freeze` block behave
@@ -19,13 +20,37 @@ export const FREEZE_STATUSES = Object.freeze(['auto', 'frozen', 'soft-advisory',
 
 /**
  * Read the normalized freeze status for an entry frontmatter.
- * Missing block / missing status / invalid value all collapse to `auto`.
+ *
+ * A missing `freeze` block, or a `freeze` block with no `status` key at all,
+ * collapses to `auto` — that permissive default is deliberate (D8): an entry
+ * that has never opted into freeze protection should never block a write.
+ *
+ * But a `freeze` block that IS present with a `status` value that is a
+ * non-empty string outside `FREEZE_STATUSES` is not "absent" — it is
+ * malformed. Coercing that case to `auto` too would silently disable hard
+ * freeze protection on a hand-edited typo (e.g. `status: Frozen` against the
+ * lowercase-only enum) with no error, no warning, and no bypass event, since
+ * the bypass path is never entered. Fail loud instead: throw so the operator
+ * fixes the typo rather than unknowingly shipping an unprotected entry.
+ *
+ * @throws {SdlabError} CANON_FREEZE_STATUS_INVALID when `freeze` is present
+ *   and `status` is a non-empty string that isn't a legal FREEZE_STATUSES value.
  */
 export function readFreezeStatus(frontmatter) {
   const status = frontmatter?.freeze?.status;
   if (typeof status !== 'string') return 'auto';
-  if (!FREEZE_STATUSES.includes(status)) return 'auto';
-  return status;
+  if (FREEZE_STATUSES.includes(status)) return status;
+  if (status.length > 0) {
+    throw inputError(
+      'CANON_FREEZE_STATUS_INVALID',
+      `Invalid freeze.status "${status}"${frontmatter?.id ? ` on entry "${frontmatter.id}"` : ''}: ` +
+        `not one of [${FREEZE_STATUSES.join(', ')}].`,
+      `Fix the freeze.status value (check for a case typo — statuses are lowercase-only). ` +
+        `A malformed status is treated as an error, not as "auto", so a typo can never ` +
+        `silently disable freeze protection.`,
+    );
+  }
+  return 'auto';
 }
 
 /**

package/lib/generated-provenance.js

@@ -9,6 +9,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHash } from 'node:crypto';
+import { warn } from './log.js';
 
 /**
  * Build a generation provenance payload for a selected output.
@@ -68,7 +69,21 @@ export function buildGeneratedProvenance({
         const brief = JSON.parse(readFileSync(briefPath, 'utf-8'));
         if (brief.subject_id) prov.subject_id = brief.subject_id;
         if (brief.parent_brief_id) prov.parent_brief_id = brief.parent_brief_id;
-      } catch { /* skip */ }
+      } catch (err) {
+        // B08: the brief exists but couldn't be read/parsed (e.g. a
+        // concurrent mid-write) — lineage is genuinely UNKNOWN here, not
+        // merely absent. Surface it instead of silently shipping
+        // provenance with no lineage and no signal that anything failed.
+        warn(`generated-provenance: brief ${briefPath} could not be read (${err.message}) — lineage_incomplete`);
+        prov.lineage_incomplete = true;
+      }
+    } else {
+      // B08: no brief on disk at all for this run — the same "genuinely
+      // unknown" lineage state as an unreadable brief, not a normal
+      // "this brief simply has no subject_id" case (that one is NOT
+      // flagged — see the brief-read-fine-but-no-subject_id branch above).
+      warn(`generated-provenance: brief not found at ${briefPath} — lineage_incomplete`);
+      prov.lineage_incomplete = true;
     }
   }