@dogfood-lab/findings 1.2.2 → 1.3.0

package/review/index.js

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

@@ -101,13 +101,34 @@ export function performAction(rootDir, params) {
 
   // Apply review metadata
   const now = new Date().toISOString();
+
+  // H4 / F-stage-a-h4 — auto-populate review.reject_reason whenever the
+  // target status is 'rejected'. Pre-amend, the engine only set the field
+  // for `action === 'reject'` and silently produced rejected findings on
+  // merge / supersede without a structured reason. The H4 schema if/then
+  // would then reject those findings at the contract boundary — but the
+  // engine was producing them. The fix:
+  //
+  //   - Operator-supplied `params.rejectReason` always wins (override).
+  //   - `merge` and `supersede` auto-default to `'merged_into_canonical'`
+  //     since lineage already carries `superseded_by` / `merged_from`.
+  //   - For `action === 'reject'`, the engine does NOT invent a default —
+  //     defaulting would erase operator intent. The schema enforces that
+  //     the field is set; an operator who forgets sees a validation error
+  //     downstream and learns to pass one. (This is the intentional
+  //     test-and-tell path in h4-engine-auto-reject-reason.test.js.)
+  let effectiveRejectReason = params.rejectReason;
+  if (!effectiveRejectReason && toStatus === 'rejected' && (action === 'merge' || action === 'supersede')) {
+    effectiveRejectReason = 'merged_into_canonical';
+  }
+
   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 } : {})
+    ...(effectiveRejectReason ? { reject_reason: effectiveRejectReason } : {})
   };
 
   // Update timestamps

package/review/transitions.js

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

@@ -1,128 +1,137 @@
-/**
- * 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, loadAcceptedPatternsWithSkips } from './recommendation-derivation.js';
+
+/**
+ * Derive doctrine from strong accepted patterns.
+ *
+ * D2B-001 — return shape carries a `skipped: [{path, error}]` field so the
+ * silent-loader signal propagates through the derive API. A torn pattern
+ * that WOULD have been considered for doctrine synthesis no longer
+ * disappears with no signal. Legacy callers reading `doctrines` / `stats`
+ * are unaffected.
+ *
+ * @param {string} rootDir - dogfood-labs repo root
+ * @returns {{ doctrines: Array, skipped: Array<{path: string, error: string}>, stats: { patternsConsidered: number, doctrinesEmitted: number, belowThreshold: number, patternsSkipped: number } }}
+ */
+export function deriveDoctrine(rootDir) {
+  const { entries, skipped } = loadAcceptedPatternsWithSkips(rootDir);
+  const patterns = entries.map(e => e.data);
+  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,
+    skipped, // D2B-001: structured skip list for operator legibility
+    stats: {
+      patternsConsidered: patterns.length,
+      doctrinesEmitted: doctrines.length,
+      belowThreshold,
+      patternsSkipped: skipped.length
+    }
+  };
+}
+
+/**
+ * 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,12 @@
-/**
- * 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, loadAcceptedPatternsWithSkips } from './recommendation-derivation.js';
+export { deriveDoctrine } from './doctrine-derivation.js';
+export { validatePattern, validateRecommendation, validateDoctrine } from './validate-artifacts.js';
+export {
+  writePattern, writeRecommendation, writeDoctrine,
+  writePatterns, writeRecommendations, writeDoctrines,
+  loadPatterns, loadRecommendations, loadDoctrines
+} from './write-artifacts.js';