@dogfood-lab/findings 1.4.0 → 1.6.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
@@ -279,6 +320,14 @@ Synthesis artifacts (patterns / recommendations / doctrine):
   doctrine <accept|reject> <id> [--actor X] [--reason Y]
   doctrine queue
 
+Advice (read-only, derived from accepted artifacts):
+  advise --surface <surface> [--execution-mode <mode>] [--repo <org/repo>] [--json]
+                                       Bootstrap guidance for a new repo/surface.
+                                       --json emits the structured advice bundle
+                                       as pure JSON (pipeable; no human text on
+                                       stdout) for shipcheck / repo-knowledge.
+  sync-export [--json]                 Export accepted artifacts for downstream sync.
+
   Note: patterns carry a literal "invalidated" status; recommendations and
   doctrine do not, so invalidate is supported for patterns only. The review /
   reopen verbs target the intermediate "reviewed" state, which the artifact
@@ -302,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);
   }
 
@@ -320,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);
@@ -349,6 +415,10 @@ Filters (for list):
       process.exit(1);
     }
 
+    if (flags.json) {
+      emitJson(buildFindingJSON(result, ROOT));
+    }
+
     console.log(formatFindingDetail(result, ROOT));
     process.exit(0);
   }
@@ -376,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)}`);
@@ -434,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);
   }
 
@@ -443,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) {
@@ -453,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);
       }
@@ -469,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);
 
@@ -703,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);
@@ -723,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);
@@ -813,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'})`);
@@ -831,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}`);
@@ -955,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}`);
@@ -971,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}`);
@@ -1048,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}]`);
@@ -1064,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}`);
@@ -1095,6 +1229,14 @@ Filters (for list):
     const bundle = generateAdviceBundle(ROOT, { surface, executionMode, repo });
     const a = bundle.advice;
 
+    // --json keeps stdout pure JSON so downstream tools (shipcheck,
+    // repo-knowledge) can pipe the structured bundle without scraping the
+    // human formatter. Matches the sync-export verb's flags.json idiom below.
+    if (flags.json) {
+      console.log(JSON.stringify(bundle, null, 2));
+      process.exit(0);
+    }
+
     console.log(`Advice for: ${[surface, executionMode, repo].filter(Boolean).join(', ') || 'general'}\n`);
 
     if (a.starter_checks.length > 0) {

package/derive/ids.js

@@ -5,17 +5,33 @@
  * No timestamp noise in IDs.
  */
 
+import { createHash } from 'node:crypto';
+
+/**
+ * Delimiter for the boundary hash: a NUL code unit cannot appear in a repo
+ * slug (`[a-zA-Z0-9_.-]`) nor in a derived lesson slug, so joining components
+ * with it means no component value can forge a false boundary between them.
+ */
+const BOUNDARY_DELIM = '\u0000';
+
 /**
  * Generate a stable finding ID from derivation context.
- * Format: dfind-<repo-slug>-<lesson-slug>
+ * Format: dfind-<repo-slug>-<lesson-slug>-<boundary-hash>
+ *
+ * The trailing boundary hash disambiguates inputs whose component boundary is
+ * itself an underscore (findings-A-002): `sanitize` folds `_` to `-`, so
+ * (repoSlug='a_b', lessonSlug='c') and (repoSlug='a', lessonSlug='b_c') both
+ * flatten the human-readable middle to `a-b-c` and previously produced the
+ * same id. The hash is computed over the components joined by BOUNDARY_DELIM,
+ * so the two tuples hash differently and never collapse to one finding_id.
  *
  * @param {string} repoSlug - e.g. "repo-crawler-mcp"
  * @param {string} lessonSlug - e.g. "surface-misclassification"
  * @returns {string}
  */
 export function generateFindingId(repoSlug, lessonSlug) {
-  const normalized = `dfind-${sanitize(repoSlug)}-${sanitize(lessonSlug)}`;
-  return normalized;
+  const boundary = boundaryHash([repoSlug, lessonSlug]);
+  return `dfind-${sanitize(repoSlug)}-${sanitize(lessonSlug)}-${boundary}`;
 }
 
 /**
@@ -46,3 +62,15 @@ function sanitize(s) {
     .replace(/-+/g, '-')
     .replace(/^-|-$/g, '');
 }
+
+/**
+ * Short stable hash of an ordered component tuple, joined by BOUNDARY_DELIM so
+ * no component value can forge a false boundary. 8 lowercase-hex chars are
+ * ample for the finding/pattern id space (a per-repo, per-lesson namespace).
+ *
+ * @param {string[]} components
+ * @returns {string}
+ */
+export function boundaryHash(components) {
+  return createHash('sha256').update(components.join(BOUNDARY_DELIM)).digest('hex').slice(0, 8);
+}

package/derive/write-findings.js

@@ -34,6 +34,7 @@ import { mkdirSync, existsSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import yaml from 'js-yaml';
 
+import { isUnsafeSegment } from '@dogfood-lab/ingest/lib/unsafe-segment.js';
 import { atomicWriteFileSync } from '../lib/atomic-write.js';
 import { validateFinding } from '../validate.js';
 
@@ -75,6 +76,26 @@ export class FindingIdCollisionError extends Error {
   }
 }
 
+/**
+ * Structured error thrown when a finding's `repo` splits into an org/repo
+ * segment that is a path-traversal vector (`..` or a path separator).
+ *
+ * findings-A-001 — write-side traversal guard. The READ side
+ * (`loadRecordsForRepoWithSkips`) already rejects such segments via
+ * `isUnsafeSegment`; the WRITE side did not, so a schema-valid
+ * `repo: '../policies'` (the dogfood-finding `repo` pattern admits `.`/`..`)
+ * resolved one level under rootDir and wrote outside `findings/`.
+ */
+export class FindingUnsafeRepoError extends Error {
+  constructor(repo, findingId) {
+    super(`unsafe repo path segment in finding${findingId ? ` (${findingId})` : ''}: '${repo}' contains a path-traversal or separator and was refused before any write (findings-A-001).`);
+    this.name = 'FindingUnsafeRepoError';
+    this.code = 'FINDING_UNSAFE_REPO';
+    this.repo = repo;
+    this.findingId = findingId;
+  }
+}
+
 /**
  * Process-level memory of ids that have already been written via
  * `writeFinding` (singleton) OR the singleton-call inside `writeFindings`
@@ -127,6 +148,13 @@ export function writeFinding(rootDir, finding) {
   const [org, repo] = (finding.repo || '').split('/');
   if (!org || !repo) throw new Error(`Invalid repo in finding: ${finding.repo}`);
 
+  // findings-A-001 — write-side path-traversal guard. Mirrors the READ side
+  // (load-records.js loadRecordsForRepoWithSkips) so a schema-valid
+  // `repo: '../policies'` cannot escape `findings/` into a sibling data dir.
+  if (isUnsafeSegment(org) || isUnsafeSegment(repo)) {
+    throw new FindingUnsafeRepoError(finding.repo, finding.finding_id);
+  }
+
   // L3-001 (Wave A2 amend2): same-process same-id refusal. Programmatic
   // callers that loop over assembleFinding output now fail-closed at the
   // singleton path, not silently at the atomicWriteFileSync.

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.4.0",
+  "version": "1.6.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

@@ -4,7 +4,7 @@
  */
 
 import { readdirSync, existsSync, statSync } from 'node:fs';
-import { resolve, join, basename, extname } from 'node:path';
+import { resolve, join, basename, extname, relative } from 'node:path';
 import { parseFinding, validateFinding } from './validate.js';
 
 /**
@@ -129,9 +129,21 @@ export function loadFindings(rootDir, opts = {}) {
  * @returns {{ path: string, data: object, valid: boolean, errors: Array } | null}
  */
 export function findById(rootDir, findingId) {
+  // B-002 — collect torn finding files encountered during the scan. The
+  // finding_id lives INSIDE the file, so a torn file cannot be matched to the
+  // requested id; if the id turns out absent from every clean file, any torn
+  // file may be the one hiding it. Surfacing them on stderr (below) mirrors the
+  // derive CLI's "N finding(s) skipped (torn/unreadable)" honesty so a torn
+  // YAML never silently masquerades as a not-found id.
+  const torn = [];
+
   // Search real findings
   for (const filePath of discoverFindings(rootDir)) {
-    const { data } = parseFinding(filePath);
+    const { data, error } = parseFinding(filePath);
+    if (error) {
+      torn.push({ path: filePath, error });
+      continue;
+    }
     if (data && data.finding_id === findingId) {
       const result = validateFinding(data);
       return { path: filePath, data, ...result };
@@ -140,21 +152,59 @@ export function findById(rootDir, findingId) {
 
   // Search valid fixtures
   for (const filePath of discoverFixtures(rootDir, 'valid')) {
-    const { data } = parseFinding(filePath);
+    const { data, error } = parseFinding(filePath);
+    if (error) {
+      torn.push({ path: filePath, error });
+      continue;
+    }
     if (data && data.finding_id === findingId) {
       const result = validateFinding(data);
       return { path: filePath, data, ...result };
     }
   }
 
+  if (torn.length > 0) {
+    // eslint-disable-next-line no-console
+    console.error(`${torn.length} finding(s) skipped (torn/unreadable):`);
+    for (const t of torn) {
+      // eslint-disable-next-line no-console
+      console.error(`  ${relative(rootDir, t.path)} — ${t.error}`);
+    }
+  }
+
   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 = {}) {
@@ -165,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/event-log.js

@@ -1,27 +1,41 @@
 /**
  * Append-only review event log.
  *
- * Events are stored as YAML arrays in reviews/<YYYY>/<date>-finding-review-log.yaml
+ * Events are stored ONE PER FILE under reviews/<YYYY>/<YYYY-MM-DD>/<event-id>.yaml
+ * (the same sharded-immutable-file pattern the records/ store uses). This
+ * replaced an earlier "daily YAML array, read-modify-rename under a file lock"
+ * design: a Phase-9 50-fork race detector proved that NO lock FILE is reliably
+ * exclusive on NTFS under heavy concurrent create churn — two appenders could
+ * both win the lock, both read N events, both rename, and one clobber the
+ * other's event (~1/3 of saturated runs, every child still exiting 0). A
+ * shared mutable array file cannot be made safe under concurrency on that fs.
+ * One immutable file per event removes the shared mutable state entirely: each
+ * append writes a uniquely-named file, so concurrent appends CANNOT collide or
+ * lose an event, and no lock is needed for correctness. `getAllEventsWithSkips`
+ * already globs reviews/ recursively and merges per-file events.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
+import { mkdirSync, existsSync, openSync, writeSync, closeSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import yaml from 'js-yaml';
 
-import { withFileLock } from '../lib/file-lock.js';
-import { renameWithRetry } from '../lib/rename-with-retry.js';
 import { loadYamlDir } from '../lib/safe-yaml-load.js';
 
 let _eventCounter = 0;
 
 /**
- * Generate a unique event ID.
+ * Generate a unique event ID. Includes a random suffix so the id is unique
+ * ACROSS processes (the `_eventCounter` is per-process, so two forks would
+ * otherwise mint the same `rev-<ts>-<seq>`); this id also names the per-event
+ * file, so cross-process uniqueness keeps two concurrent appends from picking
+ * the same filename.
  */
 export function generateEventId() {
   const ts = Date.now().toString(36);
   const seq = (++_eventCounter).toString(36).padStart(4, '0');
-  return `rev-${ts}-${seq}`;
+  const rand = randomBytes(4).toString('hex');
+  return `rev-${ts}-${seq}-${rand}`;
 }
 
 /**
@@ -71,82 +85,52 @@ export function getLogPath(rootDir, date = new Date()) {
 }
 
 /**
- * Append an event to the review log.
+ * Directory holding one date-sharded set of per-event files:
+ * reviews/<YYYY>/<YYYY-MM-DD>/. Each appended event is its own file inside.
+ */
+export function getEventDir(rootDir, date = new Date()) {
+  const year = String(date.getFullYear());
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return resolve(rootDir, 'reviews', year, `${year}-${month}-${day}`);
+}
+
+/**
+ * Append a review event by writing it to its OWN immutable file
+ * (reviews/<YYYY>/<YYYY-MM-DD>/<event-id>.yaml). See the module header for why
+ * this replaced the daily-array-under-a-lock design: no shared mutable file
+ * means concurrent appends physically cannot collide or lose an event, so no
+ * lock is needed for correctness — the Phase-9 50-fork race detector that lost
+ * an event ~1/3 of saturated runs is structurally impossible here.
  *
- * Atomicity: writes the new event list to a unique temp file then renames it
- * over the canonical log file. `rename` is atomic on POSIX and Windows, so a
- * concurrent reader sees either the old contents or the new contents — never
- * a half-written file. This also makes the operation crash-safe: a Ctrl+C
- * between read and write leaves the original log intact.
+ * Crash-safety: a single `openSync(path, 'wx')` + write of one event is atomic
+ * at the file granularity — a crash mid-write leaves a complete event file or
+ * none, never a torn shared array. The filename is the (cross-process-unique)
+ * event id, so two concurrent appends never target the same path.
  *
- * Concurrency: serialized at the choke point via `withFileLock` on the daily
- * log file (F-PIPELINE-011 / W3-PIPE-001 — Pattern #4 choke-point fix). The
- * read-then-write window is closed by holding a directory-mutex (`<logPath>.lock`)
- * across the read → push → rename sequence. Two concurrent `appendEvent` calls
- * to the SAME daily log serialize against each other; calls to DIFFERENT daily
- * logs (e.g. across a midnight boundary) do not contend. The lock is reclaimed
- * if the holder process dies — see `lib/file-lock.js` for the full design
- * rationale (why a lock dir, why not `O_APPEND`, stale recovery semantics,
- * single-machine scope).
+ * @param {string} rootDir
+ * @param {object} event - a `createEvent()` result.
+ * @returns {string} the path of the event file written.
  */
 export function appendEvent(rootDir, event) {
-  const logPath = getLogPath(rootDir);
-  const dir = dirname(logPath);
+  const dir = getEventDir(rootDir);
   mkdirSync(dir, { recursive: true });
 
-  // FAILS-then-PASSES proof gate (W3-PIPE-001):
-  // Set DISABLE_APPEND_LOCK=1 in the env to bypass the lock for the explicit
-  // purpose of demonstrating the race-detection test fails without the fix.
-  // Wave-30 receipt documents the proof: with the lock, the multi-process
-  // test passes 50/50 forks across 3 iterations, 20 consecutive test runs.
-  // With the lock disabled, the test reliably fails (rename collisions on
-  // unprotected concurrent rebuilds, dropped events).
-  if (process.env.DISABLE_APPEND_LOCK) {
-    let events = [];
-    if (existsSync(logPath)) {
-      const raw = readFileSync(logPath, 'utf-8');
-      events = yaml.load(raw) || [];
-      if (!Array.isArray(events)) events = [events];
-    }
-    events.push(event);
-    const tmpSuffix = randomBytes(4).toString('hex');
-    const tmpPath = `${logPath}.${tmpSuffix}.tmp`;
-    writeFileSync(tmpPath, yaml.dump(events, { lineWidth: 120, noRefs: true }), 'utf-8');
-    // Windows EPERM/EBUSY on rename can fire transiently when AV or
-    // Search Indexer holds a handle to the freshly written temp. Retry.
-    renameWithRetry(tmpPath, logPath);
-    return logPath;
+  const eventId = event.review_event_id || generateEventId();
+  const eventPath = resolve(dir, `${eventId}.yaml`);
+  const body = yaml.dump(event, { lineWidth: 120, noRefs: true });
+
+  // 'wx' = O_EXCL exclusive-create: asserts the unique id has not collided
+  // (it carries a random suffix, so it won't) rather than relying on it. No
+  // temp+rename is needed — there is no shared file to atomically replace; one
+  // event per file is already all-or-nothing.
+  const fd = openSync(eventPath, 'wx');
+  try {
+    writeSync(fd, body);
+  } finally {
+    closeSync(fd);
   }
-
-  return withFileLock(logPath, () => {
-    let events = [];
-    // Read-or-empty without an `existsSync` precheck: the readFileSync call
-    // either returns the bytes or throws ENOENT. Avoiding `existsSync` here
-    // closes a Windows-specific TOCTOU window where the dirent cache could
-    // report `existsSync(logPath) === false` immediately after a sibling
-    // process renamed a fresh file into place — which would cause us to
-    // start with `events = []` and silently OVERWRITE the sibling's events.
-    // The lock alone wasn't enough; the existsSync gate was the bug.
-    try {
-      const raw = readFileSync(logPath, 'utf-8');
-      const parsed = yaml.load(raw);
-      if (parsed) events = Array.isArray(parsed) ? parsed : [parsed];
-    } catch (err) {
-      if (!err || err.code !== 'ENOENT') throw err;
-    }
-
-    events.push(event);
-
-    // Atomic write: temp file → rename. Same pattern persist.js + rebuild-indexes.js use.
-    const tmpSuffix = randomBytes(4).toString('hex');
-    const tmpPath = `${logPath}.${tmpSuffix}.tmp`;
-    writeFileSync(tmpPath, yaml.dump(events, { lineWidth: 120, noRefs: true }), 'utf-8');
-    // renameWithRetry: tolerate the Windows EPERM/EBUSY transient handle race
-    // even though we hold the per-file lock — antivirus/Search Indexer can
-    // still grab a handle on the temp during the rename window.
-    renameWithRetry(tmpPath, logPath);
-    return logPath;
-  });
+  return eventPath;
 }
 
 /**

package/review/review-artifacts.js

@@ -32,10 +32,12 @@
  * partial coverage, not a silent no-op.
  */
 
+import { relative } from 'node:path';
+
 import { validateTransition, ACTION_TARGET_STATUS, REASON_REQUIRED, REQUIRES_ACCEPTED, REQUIRES_CLOSED } from './transitions.js';
 import { createEvent, appendEvent } from './event-log.js';
 import {
-  resetSeenArtifactWrites,
+  resetSeenArtifactWrite,
   writePattern,
   writeRecommendation,
   writeDoctrine,
@@ -44,6 +46,34 @@ import {
   loadDoctrinesWithSkips
 } from '../synthesis/write-artifacts.js';
 
+/**
+ * Surface torn/unreadable artifact YAML on stderr — the lookup-path analogue of
+ * the derive CLI's "N pattern(s) skipped (torn/unreadable)" reporting
+ * (cli.js) and `findRecordFile`'s stderr note (derive/load-records.js).
+ *
+ * B-001 — `findArtifactById` / `getArtifactReviewQueue` consumed only the
+ * loader's `entries`, discarding `skipped[]`. A torn artifact YAML for the very
+ * id under accept/show/queue therefore vanished behind a bare "<type> not
+ * found", giving the operator no signal that a file was unreadable. The id
+ * lives INSIDE the file, so a torn file can't be matched to a requested id;
+ * the honest signal is to name the torn files whenever any are present so the
+ * operator can distinguish "absent" from "present but unparseable". Returns the
+ * skipped list so callers can decide whether the not-found was hint-worthy.
+ *
+ * @param {string} rootDir
+ * @param {string} type - artifact kind, for the message prefix
+ * @param {Array<{ path: string, error: string }>} skipped
+ */
+function reportArtifactSkips(rootDir, type, skipped) {
+  if (!skipped || skipped.length === 0) return;
+  // eslint-disable-next-line no-console
+  console.error(`${skipped.length} ${type}(s) skipped (torn/unreadable):`);
+  for (const s of skipped) {
+    // eslint-disable-next-line no-console
+    console.error(`  ${relative(rootDir, s.path)} — ${s.error}`);
+  }
+}
+
 /**
  * Per-artifact-type configuration: the on-disk directory, the id field name,
  * the loader (with-skips) and the writer. Mirrors how the finding engine pairs
@@ -87,12 +117,15 @@ const ARTIFACT_TYPES = {
 export function findArtifactById(rootDir, type, id) {
   const cfg = ARTIFACT_TYPES[type];
   if (!cfg) return null;
-  const { entries } = cfg.loadWithSkips(rootDir);
+  const { entries, skipped } = cfg.loadWithSkips(rootDir);
   for (const entry of entries) {
     if (entry.data && entry.data[cfg.idKey] === id) {
       return { data: entry.data, path: entry.path, type };
     }
   }
+  // B-001 — id absent from the clean entries. A torn file may be hiding it;
+  // name the torn files rather than letting a bare not-found mislead.
+  reportArtifactSkips(rootDir, type, skipped);
   return null;
 }
 
@@ -217,11 +250,13 @@ export function reviewArtifact(rootDir, params) {
   });
 
   // Persist via the synthesis writer — which RE-VALIDATES the promoted artifact
-  // against its JSON Schema (fail-closed). `resetSeenArtifactWrites` is the
-  // documented opt-in for a legitimate re-write of an id already touched in this
-  // process (the synthesis collision guard otherwise refuses the second write).
+  // against its JSON Schema (fail-closed). The reset is the documented opt-in
+  // for a legitimate re-write of an id already touched in this process (the
+  // synthesis collision guard otherwise refuses the second write). B-003 —
+  // scope it to THIS id so a future batch reviewer doesn't disarm the guard for
+  // the other ids it has written this process.
   try {
-    resetSeenArtifactWrites(rootDir);
+    resetSeenArtifactWrite(rootDir, type, id);
     cfg.write(rootDir, artifact);
   } catch (err) {
     return { success: false, error: err.message, code: err.code };
@@ -249,7 +284,10 @@ export function getArtifactReviewQueue(rootDir, type) {
   for (const t of types) {
     const cfg = ARTIFACT_TYPES[t];
     if (!cfg) continue;
-    const { entries } = cfg.loadWithSkips(rootDir);
+    const { entries, skipped } = cfg.loadWithSkips(rootDir);
+    // B-001 — a torn artifact silently shrinks the review queue; name it so the
+    // operator knows the queue is partial rather than complete.
+    reportArtifactSkips(rootDir, t, skipped);
     for (const entry of entries) {
       const data = entry.data;
       if (!data) continue;

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/apply-recommendation.js

@@ -34,6 +34,7 @@ import { resolve } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import yaml from 'js-yaml';
 
+import { isUnsafeSegment } from '@dogfood-lab/ingest/lib/unsafe-segment.js';
 import { atomicWriteFileSync } from '../lib/atomic-write.js';
 import { findArtifactById } from '../review/review-artifacts.js';
 import { createEvent, appendEvent } from '../review/event-log.js';
@@ -89,6 +90,22 @@ export function applyRecommendation(rootDir, params) {
   const action = rec.action || {};
   const surfaces = rec.applies_to?.product_surfaces || [];
 
+  // findings-A-001 — path-traversal guard on the operator-supplied --policy
+  // <org/repo>. `policyPathFor` resolves `policies/repos/<org>/<repo>.yaml`; an
+  // org/repo carrying `..` or a separator would escape the policies tree on
+  // BOTH the dry-run (path leaked in preview) and write (file touched) paths,
+  // so reject here before either branch resolves a path.
+  if (params.policyRepo) {
+    const [pOrg, pRepo] = String(params.policyRepo).split('/');
+    if (!pOrg || !pRepo || isUnsafeSegment(pOrg) || isUnsafeSegment(pRepo)) {
+      return structuredError(
+        'RECOMMENDATION_UNSAFE_POLICY',
+        `policy repo "${params.policyRepo}" is not a safe org/repo path segment`,
+        'Pass --policy <org/repo> with no ".." or path separators inside the org or repo name.'
+      );
+    }
+  }
+
   // Build the resolution context shared by dry-run and write.
   const isStructured = STRUCTURED_LIST_ACTIONS.has(action.type);
   const surface = surfaces.length === 1 ? surfaces[0] : null;

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.

package/synthesis/pattern-derivation.js

@@ -8,6 +8,7 @@
  */
 
 import { loadFindings } from '../reader.js';
+import { boundaryHash } from '../derive/ids.js';
 
 /**
  * Derive candidate patterns from accepted findings.
@@ -120,7 +121,7 @@ function isFalseRecurrence(findings) {
 /**
  * Build a pattern candidate from a cluster.
  */
-function buildPatternCandidate(cluster) {
+export function buildPatternCandidate(cluster) {
   const { findings, issue_kind, root_cause_kind, remediation_kind } = cluster;
   const now = new Date().toISOString();
 
@@ -141,8 +142,16 @@ function buildPatternCandidate(cluster) {
   // 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.
+  //
+  // The human-readable slug runs `.replace(/_/g, '-')` AFTER concatenation, which folds the
+  // underscore inside a component into the same `-` that delimits components: issue_kind='a_b' +
+  // root_cause='c' and issue_kind='a' + root_cause='b_c' both flatten to `...-a-b-c`
+  // (findings-A-002). A trailing boundary hash over the UN-flattened cluster key keeps the two
+  // distinct, so legitimately different clusters no longer trip the L3-001 *_ID_COLLISION guard.
   const surfaceStr = surfaces.size === 1 ? [...surfaces][0] : 'multi-surface';
-  const slug = `${surfaceStr}-${issue_kind}-${root_cause_kind}`.replace(/_/g, '-');
+  const readable = `${surfaceStr}-${issue_kind}-${root_cause_kind}`.replace(/_/g, '-');
+  const boundary = boundaryHash([surfaceStr, issue_kind, root_cause_kind]);
+  const slug = `${readable}-${boundary}`;
 
   // Determine strength
   const strength = repos.size >= 3 ? 'strong' : repos.size >= 2 ? 'emerging' : 'emerging';

package/synthesis/write-artifacts.js

@@ -59,6 +59,24 @@ export function resetSeenArtifactWrites(rootDir) {
   }
 }
 
+/**
+ * Reset the collision memory for a SINGLE artifact id only.
+ *
+ * B-003 — `reviewArtifact` re-writes the one id it is promoting, which
+ * legitimately needs that id's guard cleared. Clearing the whole root (via
+ * `resetSeenArtifactWrites(rootDir)`) also disarms the silent-clobber guard for
+ * every OTHER kind/id — latent for a future batch caller reviewing several ids
+ * in one process. Scope the reset to `${rootDir}:${kind}:${id}` so only the id
+ * under review is cleared.
+ *
+ * @param {string} rootDir
+ * @param {'pattern'|'recommendation'|'doctrine'} kind
+ * @param {string} id
+ */
+export function resetSeenArtifactWrite(rootDir, kind, id) {
+  seenArtifactWrites.delete(`${rootDir}:${kind}:${id}`);
+}
+
 /**
  * Structured collision errors thrown by the singleton writers when called
  * twice in the same process with the same id. Mirror the batch helpers'