@dogfood-lab/findings 1.2.2 → 1.2.3

package/synthesis/recommendation-derivation.js

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

@@ -1,46 +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 })) };
-}
+/**
+ * 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

@@ -1,75 +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);
-}
+/**
+ * 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);
+}