@dogfood-lab/findings 1.2.1

package/review/event-log.js

@@ -0,0 +1,177 @@
+/**
+ * Append-only review event log.
+ *
+ * Events are stored as YAML arrays in reviews/<YYYY>/<date>-finding-review-log.yaml
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import yaml from 'js-yaml';
+
+import { withFileLock } from '../lib/file-lock.js';
+import { renameWithRetry } from '../lib/rename-with-retry.js';
+
+let _eventCounter = 0;
+
+/**
+ * Generate a unique event ID.
+ */
+export function generateEventId() {
+  const ts = Date.now().toString(36);
+  const seq = (++_eventCounter).toString(36).padStart(4, '0');
+  return `rev-${ts}-${seq}`;
+}
+
+/**
+ * Create a review event object.
+ */
+export function createEvent(params) {
+  const event = {
+    review_event_id: generateEventId(),
+    finding_id: params.findingId,
+    timestamp: new Date().toISOString(),
+    actor: params.actor,
+    action: params.action,
+    from_status: params.fromStatus,
+    to_status: params.toStatus
+  };
+
+  if (params.reason) event.reason = params.reason;
+  if (params.fieldChanges && Object.keys(params.fieldChanges).length > 0) {
+    event.field_changes = params.fieldChanges;
+  }
+  if (params.mergedFromIds?.length) event.merged_from_ids = params.mergedFromIds;
+  if (params.invalidatedBy) event.invalidated_by = params.invalidatedBy;
+  if (params.notes) event.notes = params.notes;
+
+  return event;
+}
+
+/**
+ * Get the log file path for a given date.
+ */
+export function getLogPath(rootDir, date = new Date()) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return resolve(rootDir, 'reviews', String(year), `${year}-${month}-${day}-finding-review-log.yaml`);
+}
+
+/**
+ * Append an event to the review log.
+ *
+ * Atomicity: writes the new event list to a unique temp file then renames it
+ * over the canonical log file. `rename` is atomic on POSIX and Windows, so a
+ * concurrent reader sees either the old contents or the new contents — never
+ * a half-written file. This also makes the operation crash-safe: a Ctrl+C
+ * between read and write leaves the original log intact.
+ *
+ * Concurrency: serialized at the choke point via `withFileLock` on the daily
+ * log file (F-PIPELINE-011 / W3-PIPE-001 — Pattern #4 choke-point fix). The
+ * read-then-write window is closed by holding a directory-mutex (`<logPath>.lock`)
+ * across the read → push → rename sequence. Two concurrent `appendEvent` calls
+ * to the SAME daily log serialize against each other; calls to DIFFERENT daily
+ * logs (e.g. across a midnight boundary) do not contend. The lock is reclaimed
+ * if the holder process dies — see `lib/file-lock.js` for the full design
+ * rationale (why a lock dir, why not `O_APPEND`, stale recovery semantics,
+ * single-machine scope).
+ */
+export function appendEvent(rootDir, event) {
+  const logPath = getLogPath(rootDir);
+  const dir = dirname(logPath);
+  mkdirSync(dir, { recursive: true });
+
+  // FAILS-then-PASSES proof gate (W3-PIPE-001):
+  // Set DISABLE_APPEND_LOCK=1 in the env to bypass the lock for the explicit
+  // purpose of demonstrating the race-detection test fails without the fix.
+  // Wave-30 receipt documents the proof: with the lock, the multi-process
+  // test passes 50/50 forks across 3 iterations, 20 consecutive test runs.
+  // With the lock disabled, the test reliably fails (rename collisions on
+  // unprotected concurrent rebuilds, dropped events).
+  if (process.env.DISABLE_APPEND_LOCK) {
+    let events = [];
+    if (existsSync(logPath)) {
+      const raw = readFileSync(logPath, 'utf-8');
+      events = yaml.load(raw) || [];
+      if (!Array.isArray(events)) events = [events];
+    }
+    events.push(event);
+    const tmpSuffix = randomBytes(4).toString('hex');
+    const tmpPath = `${logPath}.${tmpSuffix}.tmp`;
+    writeFileSync(tmpPath, yaml.dump(events, { lineWidth: 120, noRefs: true }), 'utf-8');
+    // Windows EPERM/EBUSY on rename can fire transiently when AV or
+    // Search Indexer holds a handle to the freshly written temp. Retry.
+    renameWithRetry(tmpPath, logPath);
+    return logPath;
+  }
+
+  return withFileLock(logPath, () => {
+    let events = [];
+    // Read-or-empty without an `existsSync` precheck: the readFileSync call
+    // either returns the bytes or throws ENOENT. Avoiding `existsSync` here
+    // closes a Windows-specific TOCTOU window where the dirent cache could
+    // report `existsSync(logPath) === false` immediately after a sibling
+    // process renamed a fresh file into place — which would cause us to
+    // start with `events = []` and silently OVERWRITE the sibling's events.
+    // The lock alone wasn't enough; the existsSync gate was the bug.
+    try {
+      const raw = readFileSync(logPath, 'utf-8');
+      const parsed = yaml.load(raw);
+      if (parsed) events = Array.isArray(parsed) ? parsed : [parsed];
+    } catch (err) {
+      if (!err || err.code !== 'ENOENT') throw err;
+    }
+
+    events.push(event);
+
+    // Atomic write: temp file → rename. Same pattern persist.js + rebuild-indexes.js use.
+    const tmpSuffix = randomBytes(4).toString('hex');
+    const tmpPath = `${logPath}.${tmpSuffix}.tmp`;
+    writeFileSync(tmpPath, yaml.dump(events, { lineWidth: 120, noRefs: true }), 'utf-8');
+    // renameWithRetry: tolerate the Windows EPERM/EBUSY transient handle race
+    // even though we hold the per-file lock — antivirus/Search Indexer can
+    // still grab a handle on the temp during the rename window.
+    renameWithRetry(tmpPath, logPath);
+    return logPath;
+  });
+}
+
+/**
+ * Read all events for a specific finding.
+ */
+export function getEventsForFinding(rootDir, findingId) {
+  const all = getAllEvents(rootDir);
+  return all.filter(e => e.finding_id === findingId);
+}
+
+/**
+ * Read all events across all findings.
+ */
+export function getAllEvents(rootDir) {
+  const reviewsDir = resolve(rootDir, 'reviews');
+  if (!existsSync(reviewsDir)) return [];
+
+  const events = [];
+  walkYaml(reviewsDir, data => {
+    if (Array.isArray(data)) events.push(...data);
+  });
+
+  return events.sort((a, b) => (a.timestamp || '').localeCompare(b.timestamp || ''));
+}
+
+/** Walk directory tree for .yaml files, parse and call cb with data. */
+function walkYaml(dir, cb) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    try {
+      if (statSync(full).isDirectory()) {
+        walkYaml(full, cb);
+      } else if (entry.endsWith('.yaml')) {
+        const raw = readFileSync(full, 'utf-8');
+        const data = yaml.load(raw);
+        if (data) cb(data);
+      }
+    } catch { /* skip bad files */ }
+  }
+}

package/review/index.js

@@ -0,0 +1,6 @@
+/**
+ * Review system exports.
+ */
+export { isLawfulTransition, validateTransition, ACTION_TARGET_STATUS, REASON_REQUIRED } from './transitions.js';
+export { createEvent, appendEvent, getEventsForFinding, getAllEvents, getLogPath, generateEventId } from './event-log.js';
+export { performAction, performMerge, getReviewQueue } from './review-engine.js';

package/review/review-engine.js

@@ -0,0 +1,288 @@
+/**
+ * Review engine for dogfood findings.
+ *
+ * Performs operator actions (accept, reject, edit, merge, reopen, invalidate, supersede)
+ * with state-machine enforcement, event logging, and artifact mutation.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import yaml from 'js-yaml';
+
+import { validateTransition, ACTION_TARGET_STATUS, REASON_REQUIRED, REQUIRES_ACCEPTED, REQUIRES_CLOSED } from './transitions.js';
+import { createEvent, appendEvent } from './event-log.js';
+import { parseFinding } from '../validate.js';
+import { findById, loadFindings } from '../reader.js';
+import { atomicWriteFileSync } from '../lib/atomic-write.js';
+
+/**
+ * Perform a review action on a finding.
+ *
+ * @param {string} rootDir - dogfood-labs repo root
+ * @param {object} params
+ * @param {string} params.findingId
+ * @param {string} params.action - review|accept|reject|edit|merge|reopen|invalidate|supersede
+ * @param {string} params.actor
+ * @param {string} [params.reason]
+ * @param {string} [params.rejectReason] - structured reject reason enum
+ * @param {object} [params.fieldChanges] - { fieldName: newValue }
+ * @param {string[]} [params.mergeSourceIds] - for merge action
+ * @param {string} [params.supersededBy] - for supersede action
+ * @param {string} [params.notes]
+ * @returns {{ success: boolean, error?: string, finding?: object, event?: object }}
+ */
+export function performAction(rootDir, params) {
+  const { findingId, action, actor } = params;
+
+  if (!findingId) return { success: false, error: 'findingId is required' };
+  if (!action) return { success: false, error: 'action is required' };
+  if (!actor) return { success: false, error: 'actor is required' };
+
+  // Load the finding
+  const result = findById(rootDir, findingId);
+  if (!result) return { success: false, error: `Finding not found: ${findingId}` };
+
+  const finding = result.data;
+  const filePath = result.path;
+  const fromStatus = finding.status;
+
+  // Enforce reason requirement
+  if (REASON_REQUIRED.has(action) && !params.reason) {
+    return { success: false, error: `Action "${action}" requires a reason` };
+  }
+
+  // Enforce accepted-only actions
+  if (REQUIRES_ACCEPTED.has(action) && fromStatus !== 'accepted') {
+    return { success: false, error: `Action "${action}" requires status "accepted", got "${fromStatus}"` };
+  }
+
+  // Enforce closed-only actions (reopen)
+  if (REQUIRES_CLOSED.has(action) && fromStatus !== 'accepted' && fromStatus !== 'rejected') {
+    return { success: false, error: `Action "${action}" requires status "accepted" or "rejected", got "${fromStatus}"` };
+  }
+
+  // Determine target status
+  let toStatus = ACTION_TARGET_STATUS[action];
+  if (toStatus === null) {
+    // Edit preserves current status
+    toStatus = fromStatus;
+  }
+
+  // Validate transition (except edit which doesn't change status)
+  if (action !== 'edit' && toStatus !== fromStatus) {
+    const transResult = validateTransition(fromStatus, toStatus);
+    if (!transResult.valid) {
+      return { success: false, error: transResult.error };
+    }
+  }
+
+  // Build field changes for edit action
+  const fieldChanges = {};
+  if (action === 'edit' && params.fieldChanges) {
+    for (const [field, newValue] of Object.entries(params.fieldChanges)) {
+      // Prototype-pollution guard: `field` is operator-supplied via CLI/API.
+      // Writing to `__proto__` / `constructor` / `prototype` would mutate
+      // Object.prototype for the review-engine process and silently corrupt
+      // every downstream YAML dump + reload. Reject these keys outright so
+      // the operator sees a structured error instead of a poisoned process.
+      if (field === '__proto__' || field === 'constructor' || field === 'prototype') {
+        return { success: false, error: `Field "${field}" is not editable (reserved/unsafe key)` };
+      }
+      const oldValue = finding[field];
+      if (oldValue !== newValue) {
+        fieldChanges[field] = { from: oldValue, to: newValue };
+        finding[field] = newValue;
+      }
+    }
+  }
+
+  // Apply status change
+  finding.status = toStatus;
+
+  // Apply review metadata
+  const now = new Date().toISOString();
+  finding.review = {
+    reviewed_by: actor,
+    reviewed_at: now,
+    last_action: action,
+    ...(params.reason ? { decision_reason: params.reason } : {}),
+    ...(params.notes ? { review_notes: params.notes } : {}),
+    ...(params.rejectReason && action === 'reject' ? { reject_reason: params.rejectReason } : {})
+  };
+
+  // Update timestamps
+  finding.updated_at = now;
+
+  // Handle invalidation
+  if (action === 'invalidate') {
+    finding.invalidation = {
+      is_invalidated: true,
+      invalidated_at: now,
+      reason: params.reason
+    };
+  }
+
+  // Handle supersede
+  if (action === 'supersede') {
+    if (!params.supersededBy) {
+      return { success: false, error: 'supersede action requires supersededBy' };
+    }
+    if (!finding.lineage) finding.lineage = {};
+    finding.lineage.superseded_by = params.supersededBy;
+  }
+
+  // Create review event
+  const event = createEvent({
+    findingId,
+    actor,
+    action,
+    fromStatus,
+    toStatus,
+    reason: params.reason,
+    fieldChanges: Object.keys(fieldChanges).length > 0 ? fieldChanges : undefined,
+    mergedFromIds: params.mergeSourceIds,
+    notes: params.notes
+  });
+
+  // Persist: update finding artifact
+  const clean = JSON.parse(JSON.stringify(finding));
+  atomicWriteFileSync(filePath, yaml.dump(clean, { lineWidth: 120, noRefs: true }));
+
+  // Persist: append event to log
+  appendEvent(rootDir, event);
+
+  return { success: true, finding, event };
+}
+
+/**
+ * Merge multiple findings into one canonical finding.
+ *
+ * @param {string} rootDir
+ * @param {object} params
+ * @param {string[]} params.sourceIds - Finding IDs to merge
+ * @param {string} params.canonicalId - Target finding ID (must exist or be one of sourceIds)
+ * @param {string} params.actor
+ * @param {string} params.reason
+ * @returns {{ success: boolean, error?: string, canonical?: object, events?: object[] }}
+ */
+export function performMerge(rootDir, params) {
+  const { sourceIds, canonicalId, actor, reason } = params;
+
+  if (!sourceIds?.length || sourceIds.length < 2) {
+    return { success: false, error: 'Merge requires at least 2 source finding IDs' };
+  }
+  if (!canonicalId) return { success: false, error: 'canonicalId is required' };
+  if (!actor) return { success: false, error: 'actor is required' };
+  if (!reason) return { success: false, error: 'Merge requires a reason' };
+
+  // Load all source findings
+  const sources = [];
+  for (const id of sourceIds) {
+    const result = findById(rootDir, id);
+    if (!result) return { success: false, error: `Source finding not found: ${id}` };
+    sources.push(result);
+  }
+
+  // Find canonical (must be one of the sources)
+  const canonicalResult = sources.find(s => s.data.finding_id === canonicalId);
+  if (!canonicalResult) {
+    return { success: false, error: `Canonical ID "${canonicalId}" must be one of the source IDs` };
+  }
+
+  const canonical = canonicalResult.data;
+  const nonCanonical = sources.filter(s => s.data.finding_id !== canonicalId);
+
+  // Merge evidence and source_record_ids into canonical
+  const mergedRecordIds = new Set(canonical.source_record_ids || []);
+  const mergedEvidence = [...(canonical.evidence || [])];
+  const mergedScenarioIds = new Set(canonical.scenario_ids || []);
+
+  for (const s of nonCanonical) {
+    for (const rid of (s.data.source_record_ids || [])) mergedRecordIds.add(rid);
+    for (const sid of (s.data.scenario_ids || [])) mergedScenarioIds.add(sid);
+    for (const ev of (s.data.evidence || [])) {
+      // Dedupe evidence by kind+record_id+scenario_id
+      const key = `${ev.evidence_kind}:${ev.record_id || ''}:${ev.scenario_id || ''}`;
+      const exists = mergedEvidence.some(e =>
+        `${e.evidence_kind}:${e.record_id || ''}:${e.scenario_id || ''}` === key
+      );
+      if (!exists) mergedEvidence.push(ev);
+    }
+  }
+
+  // Update canonical
+  canonical.source_record_ids = [...mergedRecordIds];
+  canonical.scenario_ids = [...mergedScenarioIds];
+  canonical.evidence = mergedEvidence;
+  canonical.lineage = {
+    ...(canonical.lineage || {}),
+    merged_from: nonCanonical.map(s => s.data.finding_id)
+  };
+
+  const now = new Date().toISOString();
+  canonical.updated_at = now;
+  canonical.review = {
+    reviewed_by: actor,
+    reviewed_at: now,
+    last_action: 'merge',
+    decision_reason: reason
+  };
+
+  // Write canonical
+  const cleanCanonical = JSON.parse(JSON.stringify(canonical));
+  atomicWriteFileSync(canonicalResult.path, yaml.dump(cleanCanonical, { lineWidth: 120, noRefs: true }));
+
+  // Mark source findings as rejected/superseded
+  const events = [];
+  for (const s of nonCanonical) {
+    const sourceResult = performAction(rootDir, {
+      findingId: s.data.finding_id,
+      action: 'supersede',
+      actor,
+      reason: `Merged into ${canonicalId}`,
+      supersededBy: canonicalId
+    });
+    if (sourceResult.event) events.push(sourceResult.event);
+  }
+
+  // Log merge event for canonical
+  const mergeEvent = createEvent({
+    findingId: canonicalId,
+    actor,
+    action: 'merge',
+    fromStatus: canonical.status,
+    toStatus: canonical.status,
+    reason,
+    mergedFromIds: nonCanonical.map(s => s.data.finding_id)
+  });
+  appendEvent(rootDir, mergeEvent);
+  events.push(mergeEvent);
+
+  return { success: true, canonical, events };
+}
+
+/**
+ * Get the review queue: findings needing operator attention.
+ *
+ * @param {string} rootDir
+ * @returns {Array<{ data: object, reason: string }>}
+ */
+export function getReviewQueue(rootDir) {
+  const allFindings = loadFindings(rootDir);
+  const queue = [];
+
+  for (const f of allFindings) {
+    if (!f.data) continue;
+
+    // Invalidation check first — takes priority over status-based matching
+    if (f.data.invalidation?.is_invalidated) {
+      queue.push({ data: f.data, path: f.path, queueReason: 'Invalidated — needs resolution' });
+    } else if (f.data.status === 'candidate') {
+      queue.push({ data: f.data, path: f.path, queueReason: 'Unreviewed candidate' });
+    } else if (f.data.status === 'reviewed') {
+      queue.push({ data: f.data, path: f.path, queueReason: 'Reviewed but unresolved' });
+    }
+  }
+
+  return queue;
+}

package/review/transitions.js

@@ -0,0 +1,79 @@
+/**
+ * Status transition law for findings.
+ *
+ * Lawful transitions:
+ *   candidate -> reviewed, accepted, rejected
+ *   reviewed  -> accepted, rejected
+ *   accepted  -> reviewed (via reopen/invalidate only)
+ *   accepted  -> rejected (via invalidation/reversal only)
+ *   rejected  -> reviewed (via reopen only)
+ *
+ * Forbidden:
+ *   rejected -> candidate (no rewinding to machine output)
+ *   any status -> candidate (except initial creation)
+ */
+
+const TRANSITIONS = {
+  candidate: new Set(['reviewed', 'accepted', 'rejected']),
+  reviewed:  new Set(['accepted', 'rejected']),
+  accepted:  new Set(['reviewed', 'rejected']),
+  rejected:  new Set(['reviewed'])
+};
+
+/**
+ * Check if a status transition is lawful.
+ * @param {string} from - Current status.
+ * @param {string} to - Desired status.
+ * @returns {boolean}
+ */
+export function isLawfulTransition(from, to) {
+  const allowed = TRANSITIONS[from];
+  if (!allowed) return false;
+  return allowed.has(to);
+}
+
+/**
+ * Validate a transition and return error if invalid.
+ * @param {string} from
+ * @param {string} to
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function validateTransition(from, to) {
+  if (!TRANSITIONS[from]) {
+    return { valid: false, error: `Unknown status: "${from}"` };
+  }
+  if (!isLawfulTransition(from, to)) {
+    const allowed = [...TRANSITIONS[from]].join(', ');
+    return { valid: false, error: `Cannot transition from "${from}" to "${to}". Allowed: ${allowed}` };
+  }
+  return { valid: true };
+}
+
+/**
+ * Map review actions to their target statuses.
+ */
+export const ACTION_TARGET_STATUS = {
+  review: 'reviewed',
+  accept: 'accepted',
+  reject: 'rejected',
+  edit: null,        // edit preserves current status
+  merge: 'rejected', // merged sources become rejected (merged_into_canonical)
+  reopen: 'reviewed',
+  invalidate: 'reviewed', // invalidated accepted → back to reviewed with invalidation metadata
+  supersede: 'rejected'   // superseded finding becomes rejected
+};
+
+/**
+ * Actions that require a reason.
+ */
+export const REASON_REQUIRED = new Set(['reject', 'invalidate', 'merge', 'supersede']);
+
+/**
+ * Actions that require from_status to be accepted.
+ */
+export const REQUIRES_ACCEPTED = new Set(['invalidate']);
+
+/**
+ * Actions that require from_status to be accepted or rejected.
+ */
+export const REQUIRES_CLOSED = new Set(['reopen']);

package/synthesis/doctrine-derivation.js

@@ -0,0 +1,128 @@
+/**
+ * Doctrine derivation from strong accepted patterns.
+ *
+ * Doctrine is the most conservative artifact in the system.
+ * Requirements:
+ *   - At least 1 accepted pattern (2+ for org_wide scope)
+ *   - Pattern strength must be 'strong' or 'portfolio_stable'
+ *   - Statement must be rule-like, not advisory
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import yaml from 'js-yaml';
+import { loadAcceptedPatterns } from './recommendation-derivation.js';
+
+/**
+ * Derive doctrine from strong accepted patterns.
+ *
+ * @param {string} rootDir - dogfood-labs repo root
+ * @returns {{ doctrines: Array, stats: { patternsConsidered: number, doctrinesEmitted: number, belowThreshold: number } }}
+ */
+export function deriveDoctrine(rootDir) {
+  const patterns = loadAcceptedPatterns(rootDir);
+  const strong = patterns.filter(p =>
+    p.pattern_strength === 'strong' || p.pattern_strength === 'portfolio_stable'
+  );
+
+  const doctrines = [];
+  let belowThreshold = 0;
+
+  // Group strong patterns by shared doctrine theme
+  const themes = groupByDoctrineTheme(strong);
+
+  for (const [theme, themePatterns] of themes) {
+    // org_wide doctrine requires 2+ patterns
+    const maxScope = widestScope(themePatterns);
+    if (maxScope === 'org_wide' && themePatterns.length < 2) {
+      belowThreshold++;
+      continue;
+    }
+
+    doctrines.push(buildDoctrineCandidate(theme, themePatterns));
+  }
+
+  return {
+    doctrines,
+    stats: {
+      patternsConsidered: patterns.length,
+      doctrinesEmitted: doctrines.length,
+      belowThreshold
+    }
+  };
+}
+
+/**
+ * Group patterns by doctrine theme (shared root cause family).
+ */
+function groupByDoctrineTheme(patterns) {
+  const themes = new Map();
+  for (const p of patterns) {
+    const rootCauses = p.dimensions?.root_cause_kinds || [];
+    const theme = rootCauses[0] || 'general';
+    if (!themes.has(theme)) themes.set(theme, []);
+    themes.get(theme).push(p);
+  }
+  return themes;
+}
+
+function widestScope(patterns) {
+  const order = ['repo_local', 'surface_local', 'surface_archetype', 'execution_mode', 'org_wide'];
+  let widest = 0;
+  for (const p of patterns) {
+    const idx = order.indexOf(p.transfer_scope);
+    if (idx > widest) widest = idx;
+  }
+  return order[widest];
+}
+
+function buildDoctrineCandidate(theme, patterns) {
+  const now = new Date().toISOString();
+  const issueKinds = [...new Set(patterns.flatMap(p => p.dimensions?.issue_kinds || []))];
+  const surfaces = [...new Set(patterns.flatMap(p => p.dimensions?.product_surfaces || []))];
+  const scope = widestScope(patterns);
+
+  const kind = classifyDoctrineKind(issueKinds, theme);
+  const slug = `${theme}-${kind}`.replace(/_/g, '-');
+
+  return {
+    schema_version: '1.0.0',
+    doctrine_id: `ddoc-${slug}`,
+    title: buildDoctrineTitle(theme, issueKinds, surfaces),
+    status: 'candidate',
+    doctrine_kind: kind,
+    statement: buildDoctrineStatement(theme, issueKinds, surfaces),
+    rationale: buildDoctrineRationale(patterns, theme),
+    based_on_pattern_ids: patterns.map(p => p.pattern_id),
+    transfer_scope: scope === 'repo_local' || scope === 'surface_local' ? 'surface_archetype' : scope,
+    strength: patterns.length >= 3 ? 'foundational' : 'proven',
+    created_at: now,
+    updated_at: now
+  };
+}
+
+function classifyDoctrineKind(issueKinds, theme) {
+  if (/evidence/.test(theme) || issueKinds.some(k => /evidence/.test(k))) return 'evidence_law';
+  if (/surface|interface/.test(theme)) return 'surface_law';
+  if (/policy|calibration/.test(theme)) return 'calibration_law';
+  if (/verification|provenance/.test(theme)) return 'verification_law';
+  return 'rollout_law';
+}
+
+function buildDoctrineTitle(theme, issueKinds, surfaces) {
+  const label = theme.replace(/_/g, ' ');
+  const surfaceStr = surfaces.length ? surfaces.join(', ') : 'all surfaces';
+  return `${label}: verified rule for ${surfaceStr}`;
+}
+
+function buildDoctrineStatement(theme, issueKinds, surfaces) {
+  const issueLabel = issueKinds.map(k => k.replace(/_/g, ' ')).join(' and ');
+  const surfaceStr = surfaces.length ? surfaces.join(', ') : 'all product surfaces';
+  return `Verify ${issueLabel} truth before authoring rollout assumptions for ${surfaceStr}. This is a proven recurring failure class — do not skip this step.`;
+}
+
+function buildDoctrineRationale(patterns, theme) {
+  const findingCount = patterns.reduce((sum, p) => sum + (p.support?.finding_count || 0), 0);
+  const repoCount = patterns.reduce((sum, p) => sum + (p.support?.repo_count || 0), 0);
+  return `Backed by ${patterns.length} accepted pattern(s) covering ${findingCount} findings across ${repoCount} repo(s). The ${theme.replace(/_/g, ' ')} root cause recurs independently across multiple contexts, confirming this is structural, not incidental.`;
+}

package/synthesis/index.js

@@ -0,0 +1,8 @@
+/**
+ * Synthesis layer exports.
+ */
+export { derivePatterns } from './pattern-derivation.js';
+export { deriveRecommendations, loadAcceptedPatterns } from './recommendation-derivation.js';
+export { deriveDoctrine } from './doctrine-derivation.js';
+export { validatePattern, validateRecommendation, validateDoctrine } from './validate-artifacts.js';
+export { writePattern, writeRecommendation, writeDoctrine, loadPatterns, loadRecommendations, loadDoctrines } from './write-artifacts.js';