@dogfood-lab/findings 1.2.2 → 1.2.3

package/synthesis/doctrine-derivation.js

@@ -1,128 +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.`;
-}
+/**
+ * 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

@@ -1,8 +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';
+/**
+ * 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';

package/synthesis/pattern-derivation.js

@@ -1,184 +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.`;
-}
+/**
+ * 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.`;
+}