@dogfood-lab/findings 1.5.0 → 1.7.0

package/cli.js

@@ -22,7 +22,8 @@ import {
   loadFindings,
   findById,
   filterFindings,
-  findDuplicates
+  findDuplicates,
+  matchesText
 } from './index.js';
 import {
   deriveFromRecord,
@@ -31,10 +32,15 @@ import {
   getRuleById,
   dedupeAgainstExisting,
   loadRecordById,
-  loadRecordsForRepo,
-  loadAllRecords,
   writeFindings
 } from './derive/index.js';
+// FIND-PROAC-002 — the *WithSkips loaders are not re-exported by derive/index.js
+// (it only re-exports the legacy array-shape variants); import them from the
+// concrete module via the package's ./derive/* subpath export.
+import {
+  loadRecordsForRepoWithSkips,
+  loadAllRecordsWithSkips
+} from './derive/load-records.js';
 import {
   performAction,
   performMerge,
@@ -74,7 +80,12 @@ import {
 } from './advise/index.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const ROOT = resolve(__dirname, '../..');
+// FINDINGS_REPO_ROOT lets tests (and out-of-tree operators) point the CLI at an
+// alternate data root without touching the real testing-os tree. Mirrors
+// verify/cli.js VERIFY_REPO_ROOT. Defaults to the monorepo root.
+const ROOT = process.env.FINDINGS_REPO_ROOT
+  ? resolve(process.env.FINDINGS_REPO_ROOT)
+  : resolve(__dirname, '../..');
 
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -175,6 +186,36 @@ function formatFindingDetail(f, rootDir) {
   return lines.filter(l => l !== null).join('\n');
 }
 
+/**
+ * Emit a value as pure JSON on stdout and exit 0.
+ *
+ * The read verbs' --json contract mirrors advise/sync-export: stdout is a single
+ * JSON document with NO human preamble or trailing log line, so downstream tools
+ * (shipcheck, repo-knowledge) can pipe it without scraping the text formatter.
+ */
+function emitJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+  process.exit(0);
+}
+
+/**
+ * Identity projection for a loaded finding entry.
+ *
+ * `loadFindings`/`findById` wrap each finding as { path, data, valid, errors }.
+ * The --json surface exposes the underlying finding object plus the loader's
+ * validity verdict and a repo-relative path, dropping the absolute `path` so the
+ * emitted JSON is stable across machines/checkouts. A null `data` (torn file)
+ * is preserved so a consumer sees the same skip the human stream surfaces.
+ */
+function buildFindingJSON(f, rootDir) {
+  return {
+    finding: f.data,
+    valid: f.valid,
+    errors: f.errors || [],
+    path: relative(rootDir, f.path)
+  };
+}
+
 /**
  * F2-INTEL-001 — dispatch a synthesis-artifact review subcommand.
  *
@@ -240,8 +281,8 @@ async function main() {
     console.log(`dogfood findings — finding contract spine + derivation engine
 
 Commands:
-  list                 List all findings
-  show <finding_id>    Show a single finding in detail
+  list                 List all findings (--json, --grep/--text <term>)
+  show <finding_id>    Show a single finding in detail (--json)
   validate             Validate all findings (or --file <path> for one)
   validate --all       Validate all findings + all fixtures
   derive               Derive candidate findings from records
@@ -254,8 +295,8 @@ Commands:
   merge <ids...>       Merge findings (--into <id>, --actor, --reason)
   reopen <id>          Reopen a rejected/accepted finding (--actor, --reason)
   invalidate <id>      Invalidate an accepted finding (--actor, --reason)
-  history <id>         Show review history for a finding
-  queue                Show review queue
+  history <id>         Show review history for a finding (--json)
+  queue                Show review queue (--json)
 
 Synthesis artifacts (patterns / recommendations / doctrine):
   patterns derive [--write]            Derive patterns from accepted findings
@@ -310,7 +351,16 @@ Filters (for list):
   --surface <cli|desktop|web|api|mcp-server|npm-package|plugin|library>
   --issue-kind <kind>
   --transfer-scope <scope>
-  --include-fixtures   Also list fixture findings`);
+  --grep / --text <term>   Case-insensitive substring (literal, not regex) over
+                           title / summary / doctrine_statement. ANDs with the
+                           exact-enum filters above. Also accepted by
+                           patterns/recommendations/doctrine list.
+  --include-fixtures   Also list fixture findings
+
+Structured output:
+  list, show, history, queue, and patterns/recommendations/doctrine list|show
+  accept --json to emit pure JSON (the loaded object(s)) on stdout, mirroring
+  advise --json / sync-export --json. Default human text output is unchanged.`);
     process.exit(0);
   }
 
@@ -328,9 +378,17 @@ Filters (for list):
     if (flags.surface) filters.surface = flags.surface;
     if (flags['issue-kind']) filters.issueKind = flags['issue-kind'];
     if (flags['transfer-scope']) filters.transferScope = flags['transfer-scope'];
+    // --grep / --text: free-text substring filter (case-insensitive) over the
+    // human-facing prose fields. ANDs with the exact-enum filters above.
+    const text = flags.grep || flags.text;
+    if (typeof text === 'string' && text.length > 0) filters.text = text;
 
     const filtered = filterFindings(allFindings, filters);
 
+    if (flags.json) {
+      emitJson(filtered.map(f => buildFindingJSON(f, ROOT)));
+    }
+
     if (filtered.length === 0) {
       console.log('No findings found.');
       process.exit(0);
@@ -357,6 +415,10 @@ Filters (for list):
       process.exit(1);
     }
 
+    if (flags.json) {
+      emitJson(buildFindingJSON(result, ROOT));
+    }
+
     console.log(formatFindingDetail(result, ROOT));
     process.exit(0);
   }
@@ -384,11 +446,22 @@ Filters (for list):
       }
     }
 
-    // Validate all findings + optionally fixtures
+    // Validate all findings + optionally fixtures.
+    // Verdict-first (D-OUT-001): lead with a one-line VALIDATION header so the
+    // operator knows the scope before the per-file stream scrolls, and close
+    // with a prominent VERDICT line — matching every other verdict surface in
+    // the repo (swarm findings-digest, swarm status, verify --explain).
     let failed = 0;
     let passed = 0;
 
     const realFindings = loadFindings(ROOT);
+    const fixtureCount = all
+      ? loadFindings(ROOT, { fixtures: true, fixtureKind: 'valid' }).length +
+        loadFindings(ROOT, { fixtures: true, fixtureKind: 'invalid' }).length
+      : 0;
+    const checkedCount = realFindings.length + fixtureCount;
+    console.log(`VALIDATION: ${checkedCount} findings checked`);
+
     for (const f of realFindings) {
       if (f.valid) {
         console.log(`PASS: ${relative(ROOT, f.path)}`);
@@ -442,6 +515,7 @@ Filters (for list):
     }
 
     console.log(`\n${passed} passed, ${failed} failed`);
+    console.log(failed > 0 ? `VERDICT: FAIL (${failed} failed)` : 'VERDICT: PASS');
     process.exit(failed > 0 ? 1 : 0);
   }
 
@@ -451,8 +525,13 @@ Filters (for list):
     const all = flags.all;
     const write = flags.write;
 
-    // Load records based on scope
+    // Load records based on scope. FIND-PROAC-002 — use the *WithSkips loaders
+    // so torn/unreadable record files surface as a structured skip instead of
+    // silently shrinking the dataset. A derive run over a partially-readable
+    // tree is degraded, not clean: it is reported as such (named files + a
+    // prominent skip-count line on stderr) and exits non-zero below.
     let entries = [];
+    let skippedRecords = [];
     if (recordId) {
       const entry = loadRecordById(ROOT, recordId);
       if (!entry) {
@@ -461,14 +540,18 @@ Filters (for list):
       }
       entries = [entry];
     } else if (repoKey) {
-      entries = loadRecordsForRepo(ROOT, repoKey);
-      if (entries.length === 0) {
+      const loaded = loadRecordsForRepoWithSkips(ROOT, repoKey);
+      entries = loaded.entries;
+      skippedRecords = loaded.skipped;
+      if (entries.length === 0 && skippedRecords.length === 0) {
         console.error(`No records found for repo: ${repoKey}`);
         process.exit(1);
       }
     } else if (all) {
-      entries = loadAllRecords(ROOT);
-      if (entries.length === 0) {
+      const loaded = loadAllRecordsWithSkips(ROOT);
+      entries = loaded.entries;
+      skippedRecords = loaded.skipped;
+      if (entries.length === 0 && skippedRecords.length === 0) {
         console.error('No records found.');
         process.exit(1);
       }
@@ -477,6 +560,20 @@ Filters (for list):
       process.exit(2);
     }
 
+    // FIND-PROAC-002 — surface torn/unreadable records loudly and refuse to
+    // report a clean run. Mirrors the ruleErrors block below (and the
+    // synthesis derive skip branches): name each file so it appears in CI logs,
+    // print a prominent count, exit non-zero. A torn record means the operator
+    // is deriving from an incomplete dataset — that must never look green.
+    if (skippedRecords.length > 0) {
+      console.error(`${skippedRecords.length} record(s) skipped (torn/unreadable):`);
+      for (const s of skippedRecords) {
+        console.error(`  ${relative(ROOT, s.path)} — ${s.error}`);
+      }
+      console.error('Refusing to report a clean derive run over an incomplete record set. Fix or remove the torn record(s) above and re-run.');
+      process.exit(1);
+    }
+
     // Derive
     const { candidates, ruleErrors, stats } = deriveFromRecords(entries);
 
@@ -711,6 +808,9 @@ Filters (for list):
       process.exit(2);
     }
     const events = getEventsForFinding(ROOT, findingId);
+    if (flags.json) {
+      emitJson(events);
+    }
     if (events.length === 0) {
       console.log(`No review history for: ${findingId}`);
       process.exit(0);
@@ -731,6 +831,13 @@ Filters (for list):
 
   if (command === 'queue') {
     const queue = getReviewQueue(ROOT);
+    if (flags.json) {
+      emitJson(queue.map(item => ({
+        finding: item.data,
+        queue_reason: item.queueReason,
+        path: item.path ? relative(ROOT, item.path) : undefined
+      })));
+    }
     if (queue.length === 0) {
       console.log('Review queue is empty.');
       process.exit(0);
@@ -821,7 +928,12 @@ Filters (for list):
     }
 
     if (sub === 'list') {
-      const patterns = loadPatterns(ROOT);
+      let patterns = loadPatterns(ROOT);
+      const text = flags.grep || flags.text;
+      if (typeof text === 'string' && text.length > 0) {
+        patterns = patterns.filter(p => matchesText(text, [p.title, p.summary]));
+      }
+      if (flags.json) emitJson(patterns);
       if (patterns.length === 0) { console.log('No patterns found.'); process.exit(0); }
       for (const p of patterns) {
         console.log(`[${p.status}] ${p.pattern_id} (${p.pattern_strength || 'unknown'})`);
@@ -839,6 +951,8 @@ Filters (for list):
       const p = all.find(x => x.pattern_id === id);
       if (!p) { console.error(`Pattern not found: ${id}`); process.exit(1); }
 
+      if (flags.json) emitJson(p);
+
       console.log(`Pattern:   ${p.pattern_id}`);
       console.log(`Title:     ${p.title}`);
       console.log(`Status:    ${p.status}`);
@@ -963,7 +1077,12 @@ Filters (for list):
     }
 
     if (sub === 'list') {
-      const recs = loadRecommendations(ROOT);
+      let recs = loadRecommendations(ROOT);
+      const text = flags.grep || flags.text;
+      if (typeof text === 'string' && text.length > 0) {
+        recs = recs.filter(r => matchesText(text, [r.title, r.summary]));
+      }
+      if (flags.json) emitJson(recs);
       if (recs.length === 0) { console.log('No recommendations found.'); process.exit(0); }
       for (const r of recs) {
         console.log(`[${r.status}] ${r.recommendation_id}`);
@@ -979,6 +1098,7 @@ Filters (for list):
       const all = loadRecommendations(ROOT);
       const r = all.find(x => x.recommendation_id === id);
       if (!r) { console.error(`Recommendation not found: ${id}`); process.exit(1); }
+      if (flags.json) emitJson(r);
       console.log(`Recommendation: ${r.recommendation_id}`);
       console.log(`Title:          ${r.title}`);
       console.log(`Status:         ${r.status}`);
@@ -1056,7 +1176,12 @@ Filters (for list):
     }
 
     if (sub === 'list') {
-      const docs = loadDoctrines(ROOT);
+      let docs = loadDoctrines(ROOT);
+      const text = flags.grep || flags.text;
+      if (typeof text === 'string' && text.length > 0) {
+        docs = docs.filter(d => matchesText(text, [d.title, d.statement, d.summary]));
+      }
+      if (flags.json) emitJson(docs);
       if (docs.length === 0) { console.log('No doctrine found.'); process.exit(0); }
       for (const d of docs) {
         console.log(`[${d.status}] ${d.doctrine_id} [${d.strength}]`);
@@ -1072,6 +1197,7 @@ Filters (for list):
       const all = loadDoctrines(ROOT);
       const d = all.find(x => x.doctrine_id === id);
       if (!d) { console.error(`Doctrine not found: ${id}`); process.exit(1); }
+      if (flags.json) emitJson(d);
       console.log(`Doctrine:  ${d.doctrine_id}`);
       console.log(`Title:     ${d.title}`);
       console.log(`Status:    ${d.status}`);

package/index.js

@@ -8,4 +8,4 @@
  */
 
 export { parseFinding, validateFinding, validateFindingFile } from './validate.js';
-export { discoverFindings, discoverFixtures, loadFindings, findById, filterFindings, findDuplicates } from './reader.js';
+export { discoverFindings, discoverFixtures, loadFindings, findById, filterFindings, findDuplicates, matchesText } from './reader.js';

package/lib/file-lock.js

@@ -291,14 +291,15 @@ function sleepSync(ms) {
 
 /**
  * Run `fn` while holding an exclusive lock on `targetPath`. The lock is a
- * sibling directory at `<targetPath>.lock` — see file header for the
- * full design rationale.
+ * sibling lock FILE at `<targetPath>.lock`, created via `O_EXCL` / `linkSync`
+ * compare-and-swap — see file header for the full design rationale (and why a
+ * lock file beats the earlier lock-directory design).
  *
  * The lock is per-target, so two unrelated `appendEvent` calls writing to
  * different daily log files do NOT serialize against each other.
  *
  * @template T
- * @param {string} targetPath - The file being mutated; the lock dir is `<targetPath>.lock`.
+ * @param {string} targetPath - The file being mutated; the lock file is `<targetPath>.lock`.
  * @param {() => T} fn - The critical section. Runs synchronously.
  * @param {{
  *   timeoutMs?: number,

package/lib/safe-yaml-load.js

@@ -41,6 +41,19 @@ import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
 import { join, extname } from 'node:path';
 import yaml from 'js-yaml';
 
+/**
+ * Generous defensive size cap for a single YAML/JSON document (FIND-PROAC-003).
+ *
+ * The contract files in this repo (records, findings, patterns, policies) are
+ * kilobytes, not megabytes — a multi-MB file is either corrupt or hostile, and
+ * handing it to an unbounded `yaml.load` is a silent resource cliff for every
+ * loader in the silent-loader family that delegates here. 8 MB is far above any
+ * legitimate contract document while still bounding a pathological parse. A file
+ * over the cap degrades to a structured skip (the same `{ data, error }` shape
+ * as a parse error) instead of risking the process.
+ */
+export const MAX_YAML_BYTES = 8 * 1024 * 1024;
+
 /**
  * Parse a YAML file. Returns `{ data, error }` — never throws for parse or
  * read failures.
@@ -49,6 +62,21 @@ import yaml from 'js-yaml';
  * @returns {{ data: unknown, error: string | null }}
  */
 export function loadYamlFile(filePath) {
+  // FIND-PROAC-003 — bound the parse before reading. A multi-MB YAML file is
+  // corrupt or hostile; degrade to a structured skip naming the size rather
+  // than driving an unbounded yaml.load. `stat` failures fall through to the
+  // read path so a missing file still reports the familiar "Read error: …".
+  try {
+    const { size } = statSync(filePath);
+    if (size > MAX_YAML_BYTES) {
+      return {
+        data: null,
+        error: `YAML too large: ${size} bytes exceeds ${MAX_YAML_BYTES}-byte cap (corrupt or hostile file — skipped)`
+      };
+    }
+  } catch {
+    // Defer to readFileSync for the structured error.
+  }
   let raw;
   try {
     raw = readFileSync(filePath, 'utf-8');
@@ -71,6 +99,20 @@ export function loadYamlFile(filePath) {
  * @returns {{ data: unknown, error: string | null }}
  */
 export function loadJsonFile(filePath) {
+  // FIND-PROAC-003 — same defensive size cap as loadYamlFile. Record files are
+  // JSON and travel through here; an over-cap file degrades to a structured skip
+  // naming the size instead of an unbounded JSON.parse.
+  try {
+    const { size } = statSync(filePath);
+    if (size > MAX_YAML_BYTES) {
+      return {
+        data: null,
+        error: `JSON too large: ${size} bytes exceeds ${MAX_YAML_BYTES}-byte cap (corrupt or hostile file — skipped)`
+      };
+    }
+  } catch {
+    // Defer to readFileSync for the structured error.
+  }
   let raw;
   try {
     raw = readFileSync(filePath, 'utf-8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/findings",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "type": "module",
   "description": "Finding contract spine for testing-os. Validates, reads, lists, and queries evidence-bound findings — the fourth contract alongside record, scenario, and policy.",
   "main": "index.js",

package/reader.js

@@ -175,11 +175,36 @@ export function findById(rootDir, findingId) {
   return null;
 }
 
+/**
+ * Case-insensitive substring match of `needle` against any of `haystacks`.
+ *
+ * Plain substring, not regex: a free-text `--grep` over operator-authored prose
+ * should treat `c++`, `*.yaml`, or `node --test` as literal text, not as a
+ * pattern that throws or matches surprisingly. Non-string haystacks (a missing
+ * optional field) are skipped rather than coerced.
+ *
+ * @param {string} needle - The search term (already known non-empty by caller).
+ * @param {Array<unknown>} haystacks - Candidate text fields.
+ * @returns {boolean}
+ */
+export function matchesText(needle, haystacks) {
+  const q = needle.toLowerCase();
+  for (const h of haystacks) {
+    if (typeof h === 'string' && h.toLowerCase().includes(q)) return true;
+  }
+  return false;
+}
+
 /**
  * Filter a list of loaded findings.
  *
+ * Exact-enum filters (repo/status/surface/issueKind/transferScope) and the
+ * free-text `text` filter combine with AND semantics: a finding must satisfy
+ * every supplied filter to pass. `text` is a case-insensitive substring match
+ * over the human-facing prose fields (title, summary, doctrine_statement).
+ *
  * @param {Array<{ data: object }>} findings - Loaded findings.
- * @param {{ repo?: string, status?: string, surface?: string, issueKind?: string, transferScope?: string }} filters
+ * @param {{ repo?: string, status?: string, surface?: string, issueKind?: string, transferScope?: string, text?: string }} filters
  * @returns {Array}
  */
 export function filterFindings(findings, filters = {}) {
@@ -190,6 +215,9 @@ export function filterFindings(findings, filters = {}) {
     if (filters.surface && f.data.product_surface !== filters.surface) return false;
     if (filters.issueKind && f.data.issue_kind !== filters.issueKind) return false;
     if (filters.transferScope && f.data.transfer_scope !== filters.transferScope) return false;
+    if (filters.text && !matchesText(filters.text, [f.data.title, f.data.summary, f.data.doctrine_statement])) {
+      return false;
+    }
     return true;
   });
 }

package/review/review-engine.js

@@ -11,7 +11,7 @@ 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 { parseFinding, validateFinding } from '../validate.js';
 import { findById, loadFindings } from '../reader.js';
 import { atomicWriteFileSync } from '../lib/atomic-write.js';
 
@@ -113,10 +113,12 @@ export function performAction(rootDir, params) {
   //   - `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.)
+  //     defaulting would erase operator intent. F-FIND-001 supersedes the
+  //     earlier "test-and-tell" path: rather than persisting a finding with
+  //     no reject_reason and letting the operator discover it downstream, the
+  //     write-side schema gate below refuses the write at the point of action,
+  //     so the operator gets a structured error and the canonical store never
+  //     holds a malformed finding. (See h4-engine-auto-reject-reason.test.js.)
   let effectiveRejectReason = params.rejectReason;
   if (!effectiveRejectReason && toStatus === 'rejected' && (action === 'merge' || action === 'supersede')) {
     effectiveRejectReason = 'merged_into_canonical';
@@ -165,12 +167,30 @@ export function performAction(rootDir, params) {
     notes: params.notes
   });
 
-  // Persist: update finding artifact
-  const clean = JSON.parse(JSON.stringify(finding));
-  atomicWriteFileSync(filePath, yaml.dump(clean, { lineWidth: 120, noRefs: true }));
+  // F-FIND-001 — schema gate BEFORE the filesystem touch. Every sibling
+  // finding writer (derive writeFinding, synthesis writePattern/...) validates
+  // first so no path can persist a malformed finding; the review engine was the
+  // last on-disk finding writer missing the gate. An operator edit with a
+  // typo'd enum or an unknown field is refused here instead of silently
+  // corrupting the canonical store. Return-shaped (not thrown) to match this
+  // function's `{ success, error }` contract.
+  const validation = validateFinding(finding);
+  if (!validation.valid) {
+    const summary = validation.errors.map(e => `${e.path || '/'} ${e.message}`).join('; ');
+    return { success: false, error: `Refused: edit would persist a schema-invalid finding: ${summary}` };
+  }
 
-  // Persist: append event to log
+  const clean = JSON.parse(JSON.stringify(finding));
+  const body = yaml.dump(clean, { lineWidth: 120, noRefs: true });
+
+  // F-FIND-002 — append the audit event BEFORE the artifact write. The trail is
+  // append-only and the package advertises a complete one; the unsafe
+  // asymmetry is a persisted state change with no event. Appending first means
+  // an append failure aborts before the artifact lands (no silent desync); the
+  // only residual asymmetry is an event with no state change, which the
+  // append-only reader tolerates and an operator can reconcile.
   appendEvent(rootDir, event);
+  atomicWriteFileSync(filePath, body);
 
   return { success: true, finding, event };
 }
@@ -213,6 +233,33 @@ export function performMerge(rootDir, params) {
   const canonical = canonicalResult.data;
   const nonCanonical = sources.filter(s => s.data.finding_id !== canonicalId);
 
+  // FIND-PROAC-001 — fail-closed BEFORE the canonical write. Each non-canonical
+  // source is superseded downstream via `performAction`, whose F-FIND-001
+  // write-side gate re-validates the source and can refuse. Pre-amend,
+  // `performMerge` wrote the canonical (stamping `lineage.merged_from = [X]`)
+  // and only THEN looped the supersedes, ignoring each `sourceResult.success`.
+  // A schema-invalid source X would then leave the canonical asserting it
+  // merged from X while X was never actually superseded — a lineage lie reported
+  // as `{ success: true }`. Validate every source up front; if any is invalid,
+  // refuse the whole merge naming the offending id(s) + reason so the operator
+  // can fix the source before retrying, and the canonical never records a
+  // merged_from for a source that was never superseded. Matches the canonical
+  // gate below and the singleton writers.
+  const invalidSources = [];
+  for (const s of sources) {
+    const v = validateFinding(s.data);
+    if (!v.valid) {
+      const summary = v.errors.map(e => `${e.path || '/'} ${e.message}`).join('; ');
+      invalidSources.push(`${s.data.finding_id} (${summary})`);
+    }
+  }
+  if (invalidSources.length > 0) {
+    return {
+      success: false,
+      error: `Refused: ${invalidSources.length} source finding(s) could not be superseded — fix and re-merge: ${invalidSources.join('; ')}`
+    };
+  }
+
   // Merge evidence and source_record_ids into canonical
   const mergedRecordIds = new Set(canonical.source_record_ids || []);
   const mergedEvidence = [...(canonical.evidence || [])];
@@ -249,12 +296,41 @@ export function performMerge(rootDir, params) {
     decision_reason: reason
   };
 
-  // Write canonical
+  // F-FIND-001 — schema gate the canonical BEFORE any write. The merge mutates
+  // source_record_ids / evidence / lineage / review; a malformed result must
+  // never reach disk. Matches the singleton writers and `performAction`.
+  const validation = validateFinding(canonical);
+  if (!validation.valid) {
+    const summary = validation.errors.map(e => `${e.path || '/'} ${e.message}`).join('; ');
+    return { success: false, error: `Refused: merge would persist a schema-invalid canonical: ${summary}` };
+  }
+
   const cleanCanonical = JSON.parse(JSON.stringify(canonical));
-  atomicWriteFileSync(canonicalResult.path, yaml.dump(cleanCanonical, { lineWidth: 120, noRefs: true }));
+  const canonicalBody = yaml.dump(cleanCanonical, { lineWidth: 120, noRefs: true });
 
-  // Mark source findings as rejected/superseded
+  // F-FIND-002 — append the canonical merge event BEFORE the canonical write
+  // (same ordering rationale as performAction). An append failure aborts before
+  // the canonical or any source mutation lands.
+  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);
+  atomicWriteFileSync(canonicalResult.path, canonicalBody);
+
+  // Mark source findings as rejected/superseded. Each supersede flows through
+  // performAction, so the F-FIND-001 schema gate covers these re-writes too.
+  // Sources were pre-validated above (FIND-PROAC-001), so a supersede failure
+  // here is unexpected — but never assume success. Collect any failed supersede
+  // so a partial merge is reported AS partial rather than as a clean success
+  // with a lineage that overstates what actually happened.
   const events = [];
+  const failedSupersedes = [];
   for (const s of nonCanonical) {
     const sourceResult = performAction(rootDir, {
       findingId: s.data.finding_id,
@@ -264,21 +340,22 @@ export function performMerge(rootDir, params) {
       supersededBy: canonicalId
     });
     if (sourceResult.event) events.push(sourceResult.event);
+    if (!sourceResult.success) {
+      failedSupersedes.push(`${s.data.finding_id}: ${sourceResult.error}`);
+    }
   }
 
-  // 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);
 
+  if (failedSupersedes.length > 0) {
+    return {
+      success: false,
+      error: `Partial merge: canonical ${canonicalId} was written but ${failedSupersedes.length} source(s) could not be superseded: ${failedSupersedes.join('; ')}`,
+      canonical,
+      events
+    };
+  }
+
   return { success: true, canonical, events };
 }
 

package/synthesis/doctrine-derivation.js

@@ -8,10 +8,7 @@
  *   - 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';
+import { loadAcceptedPatternsWithSkips } from './recommendation-derivation.js';
 
 /**
  * Derive doctrine from strong accepted patterns.