@dogfood-lab/findings 1.2.1

package/synthesis/pattern-derivation.js

@@ -0,0 +1,184 @@
+/**
+ * Deterministic pattern derivation from accepted findings.
+ *
+ * Clusters accepted, non-invalidated findings by shared dimensions:
+ *   issue_kind + root_cause_kind + (optionally) product_surface
+ *
+ * A pattern candidate forms when 2+ accepted findings share these dimensions.
+ */
+
+import { loadFindings } from '../reader.js';
+
+/**
+ * Derive candidate patterns from accepted findings.
+ *
+ * @param {string} rootDir - dogfood-labs repo root
+ * @param {{ includeFixtures?: boolean }} opts
+ * @returns {{ patterns: Array, stats: { findingsConsidered: number, clustersFound: number, belowThreshold: number } }}
+ */
+export function derivePatterns(rootDir, opts = {}) {
+  // Load only accepted, non-invalidated findings
+  const allFindings = loadFindings(rootDir);
+  if (opts.includeFixtures) {
+    allFindings.push(...loadFindings(rootDir, { fixtures: true, fixtureKind: 'valid' }));
+  }
+
+  const accepted = allFindings.filter(f =>
+    f.valid &&
+    f.data?.status === 'accepted' &&
+    !f.data?.invalidation?.is_invalidated
+  );
+
+  // Cluster by shared dimensions
+  const clusters = new Map();
+
+  for (const f of accepted) {
+    const d = f.data;
+    const key = buildClusterKey(d);
+
+    if (!clusters.has(key)) {
+      clusters.set(key, {
+        issue_kind: d.issue_kind,
+        root_cause_kind: d.root_cause_kind,
+        remediation_kind: d.remediation_kind,
+        findings: []
+      });
+    }
+    clusters.get(key).findings.push(d);
+  }
+
+  // Filter clusters to those meeting threshold (2+ findings)
+  const patterns = [];
+  let belowThreshold = 0;
+
+  for (const [key, cluster] of clusters) {
+    if (cluster.findings.length < 2) {
+      belowThreshold++;
+      continue;
+    }
+
+    // Check for false recurrence: all from same repo AND same source record
+    if (isFalseRecurrence(cluster.findings)) {
+      belowThreshold++;
+      continue;
+    }
+
+    patterns.push(buildPatternCandidate(cluster));
+  }
+
+  return {
+    patterns,
+    stats: {
+      findingsConsidered: accepted.length,
+      clustersFound: clusters.size,
+      belowThreshold
+    }
+  };
+}
+
+/**
+ * Build a cluster key from shared dimensions.
+ */
+function buildClusterKey(finding) {
+  return `${finding.issue_kind}::${finding.root_cause_kind}`;
+}
+
+/**
+ * Check for false recurrence: all findings from same root incident.
+ */
+function isFalseRecurrence(findings) {
+  // If all findings share exact same source_record_ids set, it's likely one incident split by extraction
+  if (findings.length < 2) return true;
+
+  const recordSets = findings.map(f => (f.source_record_ids || []).sort().join(','));
+  const unique = new Set(recordSets);
+  return unique.size === 1; // All from same records = false recurrence
+}
+
+/**
+ * Build a pattern candidate from a cluster.
+ */
+function buildPatternCandidate(cluster) {
+  const { findings, issue_kind, root_cause_kind, remediation_kind } = cluster;
+  const now = new Date().toISOString();
+
+  // Compute support dimensions
+  const repos = new Set(findings.map(f => f.repo));
+  const surfaces = new Set(findings.map(f => f.product_surface));
+  const modes = new Set(findings.flatMap(f => f.execution_mode ? [f.execution_mode] : []));
+  const remediations = new Set(findings.map(f => f.remediation_kind));
+
+  // Determine transfer scope (widest from findings)
+  const scopes = findings.map(f => f.transfer_scope);
+  const transfer_scope = widenScope(scopes);
+
+  // Determine pattern kind
+  const pattern_kind = classifyPatternKind(issue_kind);
+
+  // Build slug — must include every dimension in the cluster key (issue_kind + root_cause_kind),
+  // otherwise two clusters that differ only by root_cause_kind collide on pattern_id and the
+  // second writePattern() silently overwrites the first on disk. Surface is added for readability,
+  // not for uniqueness.
+  const surfaceStr = surfaces.size === 1 ? [...surfaces][0] : 'multi-surface';
+  const slug = `${surfaceStr}-${issue_kind}-${root_cause_kind}`.replace(/_/g, '-');
+
+  // Determine strength
+  const strength = repos.size >= 3 ? 'strong' : repos.size >= 2 ? 'emerging' : 'emerging';
+
+  return {
+    schema_version: '1.0.0',
+    pattern_id: `dpat-${slug}`,
+    title: buildPatternTitle(issue_kind, surfaces, repos.size),
+    status: 'candidate',
+    pattern_kind,
+    summary: buildPatternSummary(findings, issue_kind, root_cause_kind),
+    source_finding_ids: findings.map(f => f.finding_id),
+    support: {
+      finding_count: findings.length,
+      repo_count: repos.size,
+      surface_count: surfaces.size,
+      ...(modes.size > 0 ? { execution_modes: [...modes] } : {})
+    },
+    dimensions: {
+      product_surfaces: [...surfaces],
+      issue_kinds: [issue_kind],
+      root_cause_kinds: [root_cause_kind],
+      remediation_kinds: [...remediations]
+    },
+    transfer_scope,
+    pattern_strength: strength,
+    lineage_note: `Derived from ${findings.length} accepted findings across ${repos.size} repo(s).`,
+    created_at: now,
+    updated_at: now
+  };
+}
+
+function classifyPatternKind(issueKind) {
+  if (/evidence/.test(issueKind)) return 'evidence_calibration';
+  if (/verification|provenance/.test(issueKind)) return 'verification_seam';
+  if (/policy|freshness/.test(issueKind)) return 'calibration_signal';
+  if (/build|entrypoint|flag|interface|surface/.test(issueKind)) return 'recurring_failure';
+  return 'recurring_failure';
+}
+
+function widenScope(scopes) {
+  const order = ['repo_local', 'surface_local', 'surface_archetype', 'execution_mode', 'org_wide'];
+  let widest = 0;
+  for (const s of scopes) {
+    const idx = order.indexOf(s);
+    if (idx > widest) widest = idx;
+  }
+  return order[widest];
+}
+
+function buildPatternTitle(issueKind, surfaces, repoCount) {
+  const surfaceStr = surfaces.size === 1 ? `${[...surfaces][0]}` : `${surfaces.size} surfaces`;
+  const label = issueKind.replace(/_/g, ' ');
+  return `${label} recurs across ${repoCount} repo(s) on ${surfaceStr}`;
+}
+
+function buildPatternSummary(findings, issueKind, rootCause) {
+  const repos = [...new Set(findings.map(f => f.repo))];
+  const repoNames = repos.map(r => r.split('/').pop()).join(', ');
+  return `Multiple accepted findings show ${issueKind.replace(/_/g, ' ')} caused by ${rootCause.replace(/_/g, ' ')} across repos: ${repoNames}. This recurrence indicates a structural pattern, not isolated incidents.`;
+}

package/synthesis/recommendation-derivation.js

@@ -0,0 +1,156 @@
+/**
+ * Recommendation derivation from accepted patterns.
+ *
+ * Generates actionable guidance using constrained templates based on
+ * pattern kind, dimensions, and transfer scope.
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import yaml from 'js-yaml';
+
+/**
+ * Derive recommendations from accepted patterns.
+ *
+ * @param {string} rootDir - dogfood-labs repo root
+ * @returns {{ recommendations: Array, stats: { patternsConsidered: number, recommendationsEmitted: number } }}
+ */
+export function deriveRecommendations(rootDir) {
+  const patterns = loadAcceptedPatterns(rootDir);
+  const recommendations = [];
+
+  for (const pat of patterns) {
+    const rec = deriveFromPattern(pat);
+    if (rec) recommendations.push(rec);
+  }
+
+  return {
+    recommendations,
+    stats: {
+      patternsConsidered: patterns.length,
+      recommendationsEmitted: recommendations.length
+    }
+  };
+}
+
+/**
+ * Derive a recommendation from a single accepted pattern.
+ */
+function deriveFromPattern(pattern) {
+  const now = new Date().toISOString();
+  const template = selectTemplate(pattern);
+  if (!template) return null;
+
+  const surfaces = pattern.dimensions?.product_surfaces || [];
+  const slug = `${surfaces[0] || 'general'}-${template.kind}`.replace(/_/g, '-');
+
+  return {
+    schema_version: '1.0.0',
+    recommendation_id: `drec-${slug}-${pattern.pattern_id.replace('dpat-', '')}`,
+    title: template.titleFn(pattern),
+    status: 'candidate',
+    recommendation_kind: template.kind,
+    summary: template.summaryFn(pattern),
+    applies_to: {
+      product_surfaces: surfaces,
+      ...(pattern.support?.execution_modes?.length ? { execution_modes: pattern.support.execution_modes } : {}),
+      transfer_scope: pattern.transfer_scope
+    },
+    based_on_pattern_ids: [pattern.pattern_id],
+    action: {
+      type: template.actionType,
+      target: template.target,
+      details: template.detailsFn(pattern)
+    },
+    confidence: pattern.pattern_strength === 'strong' || pattern.pattern_strength === 'portfolio_stable' ? 'strong' : 'emerging',
+    created_at: now,
+    updated_at: now
+  };
+}
+
+/**
+ * Select the right recommendation template for a pattern.
+ */
+function selectTemplate(pattern) {
+  const kind = pattern.pattern_kind;
+  const issueKinds = pattern.dimensions?.issue_kinds || [];
+
+  if (issueKinds.some(k => /interface|surface|entrypoint|build/.test(k))) {
+    return {
+      kind: 'starter_check',
+      actionType: 'add_check',
+      target: 'rollout',
+      titleFn: (p) => `Add ${issueKinds[0].replace(/_/g, ' ')} verification to starter rollout for ${fmtSurfaces(p)}`,
+      summaryFn: (p) => `New ${fmtSurfaces(p)} repos should verify ${issueKinds[0].replace(/_/g, ' ')} before rollout assumptions are encoded into scenarios or docs. This recurs across ${p.support.repo_count} repo(s).`,
+      detailsFn: (p) => `Verify ${issueKinds[0].replace(/_/g, ' ')} contract and invocation shape before scenario authoring for ${fmtSurfaces(p)} repos.`
+    };
+  }
+
+  if (kind === 'evidence_calibration') {
+    return {
+      kind: 'evidence_expectation',
+      actionType: 'set_evidence',
+      target: 'policy',
+      titleFn: (p) => `Calibrate evidence requirements for ${fmtSurfaces(p)} based on recurring miscalibration`,
+      summaryFn: (p) => `Evidence requirements for ${fmtSurfaces(p)} have been repeatedly miscalibrated. Default to natural output types rather than forced artifact shapes.`,
+      detailsFn: (p) => `Review and adjust evidence_requirements in surface policy to match natural outputs for ${fmtSurfaces(p)} repos.`
+    };
+  }
+
+  if (kind === 'verification_seam') {
+    return {
+      kind: 'verification_rule',
+      actionType: 'set_verification',
+      target: 'verification',
+      titleFn: (p) => `Add verification guard for ${issueKinds[0]?.replace(/_/g, ' ') || 'seam'} on ${fmtSurfaces(p)}`,
+      summaryFn: (p) => `A verification seam recurs on ${fmtSurfaces(p)}. Add a guard to prevent this class of verification failure.`,
+      detailsFn: (p) => `Add verification step to detect ${issueKinds[0]?.replace(/_/g, ' ') || 'verification gap'} before acceptance.`
+    };
+  }
+
+  if (kind === 'calibration_signal') {
+    return {
+      kind: 'policy_seed',
+      actionType: 'set_policy',
+      target: 'policy',
+      titleFn: (p) => `Seed ${fmtSurfaces(p)} policy with calibrated defaults from recurring pattern`,
+      summaryFn: (p) => `Policy miscalibration recurs on ${fmtSurfaces(p)}. Seed new repo policies with proven defaults.`,
+      detailsFn: (p) => `Apply calibrated policy defaults for ${fmtSurfaces(p)} repos based on ${p.support.finding_count} proven findings.`
+    };
+  }
+
+  // Default: starter_check
+  return {
+    kind: 'starter_check',
+    actionType: 'add_check',
+    target: 'rollout',
+    titleFn: (p) => `Add check for ${issueKinds[0]?.replace(/_/g, ' ') || 'recurring issue'} on ${fmtSurfaces(p)}`,
+    summaryFn: (p) => `A recurring issue pattern was detected on ${fmtSurfaces(p)}. Add a rollout check to prevent future occurrences.`,
+    detailsFn: (p) => `Add a rollout verification step for ${issueKinds[0]?.replace(/_/g, ' ') || 'this issue class'} on ${fmtSurfaces(p)} repos.`
+  };
+}
+
+function fmtSurfaces(pattern) {
+  const s = pattern.dimensions?.product_surfaces || [];
+  return s.length ? s.join(', ') : 'general';
+}
+
+/**
+ * Load accepted patterns from disk.
+ */
+function loadAcceptedPatterns(rootDir) {
+  const dir = resolve(rootDir, 'patterns');
+  if (!existsSync(dir)) return [];
+
+  const patterns = [];
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.yaml')) continue;
+    try {
+      const data = yaml.load(readFileSync(join(dir, file), 'utf-8'));
+      if (data?.status === 'accepted') patterns.push(data);
+    } catch { /* skip */ }
+  }
+  return patterns;
+}
+
+export { loadAcceptedPatterns };

package/synthesis/validate-artifacts.js

@@ -0,0 +1,46 @@
+/**
+ * Schema validation for pattern, recommendation, and doctrine artifacts.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createRequire } from 'node:module';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import yaml from 'js-yaml';
+
+const require = createRequire(import.meta.url);
+// Resolve the schemas package's json directory via its subpath export.
+const SCHEMAS_DIR = dirname(
+  require.resolve('@dogfood-lab/schemas/json/dogfood-pattern.schema.json')
+);
+
+const _validators = {};
+
+function getValidator(schemaFile) {
+  if (!_validators[schemaFile]) {
+    const schema = JSON.parse(readFileSync(`${SCHEMAS_DIR}/${schemaFile}`, 'utf-8'));
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    _validators[schemaFile] = ajv.compile(schema);
+  }
+  return _validators[schemaFile];
+}
+
+export function validatePattern(data) {
+  const validate = getValidator('dogfood-pattern.schema.json');
+  const valid = validate(data);
+  return { valid, errors: valid ? [] : (validate.errors || []).map(e => ({ path: e.instancePath || '/', message: e.message })) };
+}
+
+export function validateRecommendation(data) {
+  const validate = getValidator('dogfood-recommendation.schema.json');
+  const valid = validate(data);
+  return { valid, errors: valid ? [] : (validate.errors || []).map(e => ({ path: e.instancePath || '/', message: e.message })) };
+}
+
+export function validateDoctrine(data) {
+  const validate = getValidator('dogfood-doctrine.schema.json');
+  const valid = validate(data);
+  return { valid, errors: valid ? [] : (validate.errors || []).map(e => ({ path: e.instancePath || '/', message: e.message })) };
+}

package/synthesis/write-artifacts.js

@@ -0,0 +1,75 @@
+/**
+ * Write pattern, recommendation, and doctrine artifacts to disk.
+ */
+
+import { mkdirSync, existsSync, readdirSync, readFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import yaml from 'js-yaml';
+
+import { atomicWriteFileSync } from '../lib/atomic-write.js';
+
+/**
+ * Write a pattern to disk.
+ */
+export function writePattern(rootDir, pattern) {
+  const dir = resolve(rootDir, 'patterns');
+  mkdirSync(dir, { recursive: true });
+  const path = resolve(dir, `${pattern.pattern_id}.yaml`);
+  atomicWriteFileSync(path, yaml.dump(JSON.parse(JSON.stringify(pattern)), { lineWidth: 120, noRefs: true }));
+  return path;
+}
+
+/**
+ * Write a recommendation to disk.
+ */
+export function writeRecommendation(rootDir, rec) {
+  const dir = resolve(rootDir, 'recommendations');
+  mkdirSync(dir, { recursive: true });
+  const path = resolve(dir, `${rec.recommendation_id}.yaml`);
+  atomicWriteFileSync(path, yaml.dump(JSON.parse(JSON.stringify(rec)), { lineWidth: 120, noRefs: true }));
+  return path;
+}
+
+/**
+ * Write a doctrine to disk.
+ */
+export function writeDoctrine(rootDir, doc) {
+  const dir = resolve(rootDir, 'doctrine');
+  mkdirSync(dir, { recursive: true });
+  const path = resolve(dir, `${doc.doctrine_id}.yaml`);
+  atomicWriteFileSync(path, yaml.dump(JSON.parse(JSON.stringify(doc)), { lineWidth: 120, noRefs: true }));
+  return path;
+}
+
+/**
+ * Load all patterns from disk.
+ */
+export function loadPatterns(rootDir) {
+  return loadArtifacts(resolve(rootDir, 'patterns'));
+}
+
+/**
+ * Load all recommendations from disk.
+ */
+export function loadRecommendations(rootDir) {
+  return loadArtifacts(resolve(rootDir, 'recommendations'));
+}
+
+/**
+ * Load all doctrines from disk.
+ */
+export function loadDoctrines(rootDir) {
+  return loadArtifacts(resolve(rootDir, 'doctrine'));
+}
+
+function loadArtifacts(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter(f => f.endsWith('.yaml'))
+    .map(f => {
+      try {
+        return yaml.load(readFileSync(join(dir, f), 'utf-8'));
+      } catch { return null; }
+    })
+    .filter(Boolean);
+}

package/validate.js

@@ -0,0 +1,87 @@
+/**
+ * Finding schema validator.
+ * Validates YAML finding files against dogfood-finding.schema.json.
+ */
+
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import yaml from 'js-yaml';
+
+const require = createRequire(import.meta.url);
+
+/** Load and compile the finding schema once. */
+function createValidator() {
+  const schemaPath = require.resolve('@dogfood-lab/schemas/json/dogfood-finding.schema.json');
+  const schema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
+
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+
+  return ajv.compile(schema);
+}
+
+let _validator = null;
+
+function getValidator() {
+  if (!_validator) {
+    _validator = createValidator();
+  }
+  return _validator;
+}
+
+/**
+ * Parse a YAML finding file and return the data.
+ * @param {string} filePath - Absolute path to a .yaml finding file.
+ * @returns {{ data: object | null, error: string | null }}
+ */
+export function parseFinding(filePath) {
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const data = yaml.load(raw);
+    if (!data || typeof data !== 'object') {
+      return { data: null, error: 'File did not parse to an object' };
+    }
+    return { data, error: null };
+  } catch (err) {
+    return { data: null, error: `YAML parse error: ${err.message}` };
+  }
+}
+
+/**
+ * Validate a parsed finding object against the schema.
+ * @param {object} finding - Parsed finding data.
+ * @returns {{ valid: boolean, errors: Array<{ path: string, message: string }> }}
+ */
+export function validateFinding(finding) {
+  const validate = getValidator();
+  const valid = validate(finding);
+
+  if (valid) {
+    return { valid: true, errors: [] };
+  }
+
+  const errors = (validate.errors || []).map(err => ({
+    path: err.instancePath || '/',
+    message: err.message || 'unknown error',
+    params: err.params
+  }));
+
+  return { valid: false, errors };
+}
+
+/**
+ * Parse and validate a YAML finding file in one call.
+ * @param {string} filePath - Absolute path to a .yaml finding file.
+ * @returns {{ valid: boolean, data: object | null, errors: Array<{ path: string, message: string }> }}
+ */
+export function validateFindingFile(filePath) {
+  const { data, error } = parseFinding(filePath);
+  if (error) {
+    return { valid: false, data: null, errors: [{ path: '/', message: error }] };
+  }
+
+  const result = validateFinding(data);
+  return { ...result, data };
+}