@dogfood-lab/findings 1.3.1 → 1.4.0

package/README.md

@@ -58,8 +58,62 @@ if (!result.ok) {
 | Derive | `derive/derive-findings.js` | New finding files under `findings/`; deduplication via `derive/dedupe.js` |
 | Review | `review/review-engine.js` | Status transitions + `event-log.jsonl` audit trail |
 | Synthesize | `synthesis/pattern-derivation.js`, `synthesis/recommendation-derivation.js`, `synthesis/doctrine-derivation.js` | Pattern, recommendation, doctrine artifacts |
+| Review (artifacts) | `review/review-artifacts.js` | Promotes a synthesis-artifact `candidate` → `accepted` so it reaches the advise surface |
 | Advise | `advise/advice-bundle.js`, `advise/query.js` | Advisory bundles for downstream consumers (e.g., `@dogfood-lab/dogfood-swarm`) |
 
+### Closing the intelligence loop
+
+Synthesis writes patterns, recommendations, and doctrine with `status: 'candidate'`,
+but the advise layer (`queryPatterns` / `queryRecommendations` / `queryDoctrine`)
+surfaces only `accepted` artifacts. The artifact review verbs are what promote a
+candidate so the intelligence layer actually reaches future projects:
+
+```bash
+# Promote a derived pattern into the advise surface (accept = the loop closes)
+npx @dogfood-lab/findings patterns accept dpat-xxxx --actor mike --reason "sound recurrence"
+
+# Same for recommendations and doctrine
+npx @dogfood-lab/findings recommendations accept drec-xxxx --actor mike
+npx @dogfood-lab/findings doctrine accept ddoc-xxxx --actor mike
+
+# Retire an accepted pattern when source truth changes (patterns only)
+npx @dogfood-lab/findings patterns invalidate dpat-xxxx --actor mike --reason "source changed"
+
+# See what is awaiting review
+npx @dogfood-lab/findings patterns queue
+```
+
+The artifact review law reuses the finding status law (`review/transitions.js`).
+Patterns carry a literal `invalidated` status; recommendations and doctrine do
+not, so `invalidate` is supported for patterns only. `review` / `reopen` target
+the intermediate `reviewed` state, which the artifact schemas do not allow — they
+are refused honestly rather than writing a schema-invalid artifact.
+
+**Re-derivation safety:** re-running `<type> derive --write` will not overwrite an
+artifact you have already promoted. A freshly-derived `candidate` that collides
+with an accepted / rejected / invalidated id is preserved, not clobbered
+(`synthesis/dedupe-artifacts.js`, mirroring `derive/dedupe.js`).
+
+### Applying a recommendation back into a policy
+
+An **accepted** recommendation whose action is a structured `add_scenario` /
+`add_check` can be applied directly into a named repo policy:
+
+```bash
+# Preview the change (default — writes nothing)
+npx @dogfood-lab/findings recommendations apply drec-xxxx --policy mcp-tool-shop-org/widget
+
+# Apply the structured intent: add the target scenario id to the policy's
+# required_scenarios for the recommendation's surface, recording provenance
+npx @dogfood-lab/findings recommendations apply drec-xxxx --write --policy mcp-tool-shop-org/widget --actor mike
+```
+
+This is honest partial automation. Only the structured `target` id is applied;
+the free-text `action.details` is recorded as provenance and **never** injected as
+policy logic. Free-text-only action types (`set_policy`, `set_evidence`, …) and
+ambiguous targets (no named policy, multiple surfaces) refuse `--write` with a
+structured `{ code, message, hint }` telling the operator to apply manually.
+
 ## Finding shape
 
 ```yaml

package/cli.js

@@ -41,6 +41,12 @@ import {
   getReviewQueue,
   getEventsForFinding
 } from './review/index.js';
+import {
+  reviewArtifact,
+  findArtifactById,
+  getArtifactReviewQueue
+} from './review/review-artifacts.js';
+import { applyRecommendation } from './synthesis/apply-recommendation.js';
 import {
   derivePatterns,
   deriveRecommendations,
@@ -56,7 +62,11 @@ import {
   writeDoctrines,
   loadPatterns,
   loadRecommendations,
-  loadDoctrines
+  loadDoctrines,
+  loadPatternsWithSkips,
+  loadRecommendationsWithSkips,
+  loadDoctrinesWithSkips,
+  dedupeArtifactsAgainstExisting
 } from './synthesis/index.js';
 import {
   generateAdviceBundle,
@@ -165,6 +175,64 @@ function formatFindingDetail(f, rootDir) {
   return lines.filter(l => l !== null).join('\n');
 }
 
+/**
+ * F2-INTEL-001 — dispatch a synthesis-artifact review subcommand.
+ *
+ * Mirrors the finding review dispatch (the `['accept','reject','review',
+ * 'reopen','invalidate']` block below) but routes to `reviewArtifact`. Returns
+ * `true` when it handled the subcommand (and has already exited), `false`
+ * when `sub` was not a review verb so the caller can fall through to
+ * derive/list/show/etc.
+ *
+ * `type` is the artifact family ('pattern'|'recommendation'|'doctrine').
+ */
+const ARTIFACT_REVIEW_VERBS = ['accept', 'reject', 'review', 'reopen', 'invalidate'];
+
+function handleArtifactReview(type, sub, positional, flags) {
+  if (sub === 'queue') {
+    const queue = getArtifactReviewQueue(ROOT, type);
+    if (queue.length === 0) {
+      console.log(`${type} review queue is empty.`);
+      process.exit(0);
+    }
+    console.log(`${type} review queue (${queue.length} item(s)):\n`);
+    for (const item of queue) {
+      const id = item.data.pattern_id || item.data.recommendation_id || item.data.doctrine_id;
+      console.log(`  [${item.data.status}] ${id}`);
+      console.log(`    ${item.queueReason}`);
+      console.log(`    ${item.data.title}`);
+      console.log();
+    }
+    process.exit(0);
+  }
+
+  if (!ARTIFACT_REVIEW_VERBS.includes(sub)) return false;
+
+  const id = positional[1];
+  if (!id) {
+    console.error(`Usage: dogfood findings ${type === 'doctrine' ? 'doctrine' : type + 's'} ${sub} <id> --actor <name> [--reason "..."]`);
+    process.exit(2);
+  }
+  const actor = flags.actor || 'operator';
+  const result = reviewArtifact(ROOT, {
+    type,
+    id,
+    action: sub,
+    actor,
+    reason: flags.reason,
+    notes: flags.notes
+  });
+  if (!result.success) {
+    console.error(`FAILED: ${result.error}`);
+    process.exit(1);
+  }
+  console.log(`${sub}: ${id} → ${result.artifact.status}`);
+  if (result.event) {
+    console.log(`Event: ${result.event.review_event_id} (${result.event.from_status} → ${result.event.to_status})`);
+  }
+  process.exit(0);
+}
+
 async function main() {
   const { command, positional, flags } = parseArgs(process.argv);
 
@@ -189,6 +257,33 @@ Commands:
   history <id>         Show review history for a finding
   queue                Show review queue
 
+Synthesis artifacts (patterns / recommendations / doctrine):
+  patterns derive [--write]            Derive patterns from accepted findings
+  patterns list|show <id>              List / inspect patterns
+  patterns <accept|reject|invalidate> <id> [--actor X] [--reason Y]
+                                       Review a pattern — accept PROMOTES a
+                                       candidate into the advise surface
+                                       (queryPatterns). Closes the loop.
+  patterns queue                       Patterns awaiting review (candidates)
+  recommendations derive [--write] | list | show <id>
+  recommendations <accept|reject> <id> [--actor X] [--reason Y]
+  recommendations apply <id> [--dry-run | --write] [--policy <org/repo>] [--actor X]
+                                       Apply an ACCEPTED recommendation back into
+                                       a repo policy. --dry-run (default) previews;
+                                       --write adds the structured target id to the
+                                       named policy's required_scenarios and records
+                                       provenance. Free-text-only / ambiguous intent
+                                       is refused with a structured hint.
+  recommendations queue
+  doctrine derive [--write] | list | show <id>
+  doctrine <accept|reject> <id> [--actor X] [--reason Y]
+  doctrine queue
+
+  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
+  schemas do not allow — they are refused honestly for artifacts.
+
 Derive options:
   --record <run_id>    Derive from a specific record
   --repo <org/repo>    Derive from all records for a repo
@@ -196,6 +291,11 @@ Derive options:
   --dry-run            Show what would be emitted (default)
   --write              Write candidates to disk
 
+Re-derivation safety:
+  A re-run of "<type> derive --write" will NOT overwrite an artifact you have
+  already promoted (accepted / rejected / invalidated). Such ids are reported as
+  "Preserved (operator-promoted, not overwritten)".
+
 Filters (for list):
   --repo <org/repo>
   --status <candidate|reviewed|accepted|rejected>
@@ -641,9 +741,23 @@ Filters (for list):
 
   if (command === 'patterns') {
     const sub = positional[0];
+    // F2-INTEL-001 — review verbs (accept/reject/review/reopen/invalidate) + queue.
+    handleArtifactReview('pattern', sub, positional, flags);
     if (sub === 'derive') {
       const write = flags.write;
-      const { patterns, stats } = derivePatterns(ROOT, { includeFixtures: flags['include-fixtures'] });
+      const { patterns, skipped, stats } = derivePatterns(ROOT, { includeFixtures: flags['include-fixtures'] });
+
+      // D2B-001 — surface structured skip signal to operators. A torn accepted
+      // finding silently shrinks the evidence base behind a pattern's strength
+      // or threshold; print which file was unreadable so it appears in CI logs.
+      // Mirrors the recommendations/doctrine derive branches. Exit stays 0 —
+      // partial derivation still completes honestly against the clean findings.
+      if (skipped && skipped.length > 0) {
+        console.error(`${skipped.length} finding(s) skipped (torn/unreadable):`);
+        for (const s of skipped) {
+          console.error(`  ${relative(ROOT, s.path)} — ${s.error}`);
+        }
+      }
 
       // Validate all
       const invalid = patterns.filter(p => !validatePattern(p).valid);
@@ -668,8 +782,20 @@ Filters (for list):
         console.log();
       }
 
-      if (write && patterns.length > 0) {
-        const { written, errors } = writePatterns(ROOT, patterns);
+      // F2-INTEL-002 — preserve operator status across re-derivation. A
+      // freshly-derived candidate must NOT clobber an existing promoted
+      // (reviewed/accepted/rejected/invalidated) pattern on disk.
+      const { entries: existingPatterns } = loadPatternsWithSkips(ROOT);
+      const { toWrite, collisions } = dedupeArtifactsAgainstExisting(patterns, existingPatterns, 'pattern_id');
+      if (collisions.length > 0) {
+        console.log(`Preserved (operator-promoted, not overwritten): ${collisions.length}`);
+        for (const c of collisions) {
+          console.log(`  ${c.id} (existing status: ${c.existingStatus})`);
+        }
+      }
+
+      if (write && toWrite.length > 0) {
+        const { written, errors } = writePatterns(ROOT, toWrite);
         for (const p of written) {
           console.log(`Written: ${relative(ROOT, p)}`);
         }
@@ -680,8 +806,8 @@ Filters (for list):
           }
           process.exit(1);
         }
-      } else if (!write && patterns.length > 0) {
-        console.log(`(dry-run) ${patterns.length} pattern(s) would be written. Use --write to materialize.`);
+      } else if (!write && toWrite.length > 0) {
+        console.log(`(dry-run) ${toWrite.length} pattern(s) would be written. Use --write to materialize.`);
       }
       process.exit(0);
     }
@@ -719,12 +845,56 @@ Filters (for list):
       process.exit(0);
     }
 
-    console.error('Usage: dogfood findings patterns <derive|list|show|explain> [options]');
+    console.error('Usage: dogfood findings patterns <derive|list|show|explain|accept|reject|invalidate|queue> [options]');
     process.exit(2);
   }
 
   if (command === 'recommendations') {
     const sub = positional[0];
+    // F2-INTEL-001 — review verbs (accept/reject/review/reopen/invalidate) + queue.
+    handleArtifactReview('recommendation', sub, positional, flags);
+
+    // F2-INTEL-003 — apply an accepted recommendation back into a policy.
+    if (sub === 'apply') {
+      const id = positional[1];
+      if (!id) {
+        console.error('Usage: dogfood findings recommendations apply <id> [--dry-run | --write] [--policy <org/repo>] [--actor <name>]');
+        process.exit(2);
+      }
+      const mode = flags.write ? 'write' : 'dry-run';
+      const res = applyRecommendation(ROOT, {
+        id,
+        mode,
+        actor: flags.actor || 'operator',
+        policyRepo: flags.policy
+      });
+      if (!res.success) {
+        // Structured { code, message, hint } error.
+        console.error(`FAILED [${res.error.code}]: ${res.error.message}`);
+        if (res.error.hint) console.error(`Hint: ${res.error.hint}`);
+        process.exit(1);
+      }
+      if (mode === 'write') {
+        if (res.alreadyPresent) {
+          console.log(`apply: ${id} — "${res.provenance.target}" already present in ${flags.policy} surface ${res.provenance.surface} (no change).`);
+        } else {
+          console.log(`apply: ${id} → added "${res.provenance.target}" to ${flags.policy} surface ${res.provenance.surface}.`);
+        }
+        console.log(`Provenance: recommendation_id=${res.provenance.recommendation_id} (details recorded, not injected as logic)`);
+      } else {
+        const p = res.preview;
+        console.log(`(dry-run) recommendation ${id}`);
+        console.log(`  Action:   ${p.actionType}  target=${p.target}`);
+        console.log(`  Surface:  ${p.surface || '(' + p.surfaces.join(', ') + ' — ambiguous)'}`);
+        if (p.policyPath) console.log(`  Policy:   ${relative(ROOT, p.policyPath)}`);
+        if (p.field) console.log(`  Field:    ${p.field}`);
+        console.log(`  ${p.note}`);
+        console.log(`  Details (free-text, provenance only): ${p.details}`);
+        console.log(`\n${p.autoApplicable ? 'Auto-applicable.' : 'Not auto-applicable.'} Use --write [--policy <org/repo>] to apply the structured intent.`);
+      }
+      process.exit(0);
+    }
+
     if (sub === 'derive') {
       const write = flags.write;
       const { recommendations, skipped, stats } = deriveRecommendations(ROOT);
@@ -732,6 +902,14 @@ Filters (for list):
       // D2B-001 — surface structured skip signal to operators. The derive
       // engine still emits clean recommendations from the patterns it could
       // read; the skipped list documents the partial-completion honestly.
+      //
+      // B003 (conscious decision): skips are NON-FATAL by design — this branch
+      // prints them to stderr but keeps exit 0, unlike the `derive` branch
+      // which exits 1 on ruleErrors (cli.js:376-382). That asymmetry is
+      // intentional: a torn input here degrades the synthesis corpus rather
+      // than corrupting it, and `findings validate` is the gate that fails the
+      // run on torn inputs. Do not convert this to exit 1 without a `--strict`
+      // opt-in; CI that must block on torn inputs should run `validate`.
       if (skipped && skipped.length > 0) {
         console.error(`${skipped.length} pattern(s) skipped (torn/unreadable):`);
         for (const s of skipped) {
@@ -748,8 +926,18 @@ Filters (for list):
         console.log();
       }
 
-      if (write && recommendations.length > 0) {
-        const { written, errors } = writeRecommendations(ROOT, recommendations);
+      // F2-INTEL-002 — preserve operator status across re-derivation.
+      const { entries: existingRecs } = loadRecommendationsWithSkips(ROOT);
+      const { toWrite, collisions } = dedupeArtifactsAgainstExisting(recommendations, existingRecs, 'recommendation_id');
+      if (collisions.length > 0) {
+        console.log(`Preserved (operator-promoted, not overwritten): ${collisions.length}`);
+        for (const c of collisions) {
+          console.log(`  ${c.id} (existing status: ${c.existingStatus})`);
+        }
+      }
+
+      if (write && toWrite.length > 0) {
+        const { written, errors } = writeRecommendations(ROOT, toWrite);
         for (const p of written) {
           console.log(`Written: ${relative(ROOT, p)}`);
         }
@@ -760,8 +948,8 @@ Filters (for list):
           }
           process.exit(1);
         }
-      } else if (!write && recommendations.length > 0) {
-        console.log(`(dry-run) ${recommendations.length} recommendation(s) would be written. Use --write to materialize.`);
+      } else if (!write && toWrite.length > 0) {
+        console.log(`(dry-run) ${toWrite.length} recommendation(s) would be written. Use --write to materialize.`);
       }
       process.exit(0);
     }
@@ -796,17 +984,24 @@ Filters (for list):
       process.exit(0);
     }
 
-    console.error('Usage: dogfood findings recommendations <derive|list|show> [options]');
+    console.error('Usage: dogfood findings recommendations <derive|list|show|apply|accept|reject|invalidate|queue> [options]');
     process.exit(2);
   }
 
   if (command === 'doctrine') {
     const sub = positional[0];
+    // F2-INTEL-001 — review verbs (accept/reject/review/reopen/invalidate) + queue.
+    handleArtifactReview('doctrine', sub, positional, flags);
     if (sub === 'derive') {
       const write = flags.write;
       const { doctrines, skipped, stats } = deriveDoctrine(ROOT);
 
       // D2B-001 — surface structured skip signal to operators.
+      //
+      // B003 (conscious decision): skips are NON-FATAL by design — printed to
+      // stderr but exit stays 0 (see the matching note on the recommendations
+      // derive branch). `findings validate` is the gate that fails on torn
+      // inputs; do not convert this to exit 1 without a `--strict` opt-in.
       if (skipped && skipped.length > 0) {
         console.error(`${skipped.length} pattern(s) skipped (torn/unreadable):`);
         for (const s of skipped) {
@@ -824,8 +1019,18 @@ Filters (for list):
         console.log();
       }
 
-      if (write && doctrines.length > 0) {
-        const { written, errors } = writeDoctrines(ROOT, doctrines);
+      // F2-INTEL-002 — preserve operator status across re-derivation.
+      const { entries: existingDoctrines } = loadDoctrinesWithSkips(ROOT);
+      const { toWrite, collisions } = dedupeArtifactsAgainstExisting(doctrines, existingDoctrines, 'doctrine_id');
+      if (collisions.length > 0) {
+        console.log(`Preserved (operator-promoted, not overwritten): ${collisions.length}`);
+        for (const c of collisions) {
+          console.log(`  ${c.id} (existing status: ${c.existingStatus})`);
+        }
+      }
+
+      if (write && toWrite.length > 0) {
+        const { written, errors } = writeDoctrines(ROOT, toWrite);
         for (const p of written) {
           console.log(`Written: ${relative(ROOT, p)}`);
         }
@@ -836,8 +1041,8 @@ Filters (for list):
           }
           process.exit(1);
         }
-      } else if (!write && doctrines.length > 0) {
-        console.log(`(dry-run) ${doctrines.length} doctrine(s) would be written. Use --write to materialize.`);
+      } else if (!write && toWrite.length > 0) {
+        console.log(`(dry-run) ${toWrite.length} doctrine(s) would be written. Use --write to materialize.`);
       }
       process.exit(0);
     }
@@ -871,7 +1076,7 @@ Filters (for list):
       process.exit(0);
     }
 
-    console.error('Usage: dogfood findings doctrine <derive|list|show> [options]');
+    console.error('Usage: dogfood findings doctrine <derive|list|show|accept|reject|queue> [options]');
     process.exit(2);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/findings",
-  "version": "1.3.1",
+  "version": "1.4.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",
@@ -18,7 +18,7 @@
     "findings": "./cli.js"
   },
   "scripts": {
-    "test": "node --test findings.test.js derive/derive.test.js derive/load-records-skip.test.js derive/d2b-008-collision-guard.test.js derive/d2b-002-write-schema-gate.test.js review/review.test.js review/event-log-loader.test.js review/h4-engine-auto-reject-reason.test.js synthesis/synthesis.test.js synthesis/loaders-skip.test.js synthesis/d2b-001-derive-skipped-signal.test.js advise/advise.test.js lib/atomic-write.test.js lib/safe-yaml-load.test.js lib/d1b-002-findings-sleepsync.test.js"
+    "test": "node --test findings.test.js derive/derive.test.js derive/load-records-skip.test.js derive/d2b-008-collision-guard.test.js derive/d2b-002-write-schema-gate.test.js review/review.test.js review/event-log-loader.test.js review/h4-engine-auto-reject-reason.test.js review/featF-intel-001-review-artifacts.test.js review/featF-intel-001-cli.test.js synthesis/synthesis.test.js synthesis/loaders-skip.test.js synthesis/d2b-001-derive-skipped-signal.test.js synthesis/featF-intel-002-preserve-operator-status.test.js synthesis/featF-intel-003-apply-recommendation.test.js advise/advise.test.js lib/atomic-write.test.js lib/safe-yaml-load.test.js lib/d1b-002-findings-sleepsync.test.js"
   },
   "files": [
     "index.js",

package/reader.js

@@ -25,7 +25,18 @@ export function discoverFindings(rootDir) {
     const orgDir = join(findingsDir, org);
     for (const repo of listDirs(orgDir)) {
       const repoDir = join(orgDir, repo);
-      for (const file of readdirSync(repoDir)) {
+      // Leaf-IO guard (B002): the two OUTER levels go through `listDirs`, whose
+      // statSync is wrapped in try/catch so one unreadable dir is skipped. The
+      // innermost leaf read was bare — a single repo dir going unreadable
+      // (EACCES on a locked/permission-restricted dir, an ENOTDIR, a transient
+      // FS error) would throw an unstructured Node stack out of discoverFindings
+      // and hence out of every consumer (validate / list / derivePatterns /
+      // advise / review queue), so one bad directory sank discovery for EVERY
+      // other repo. Mirror the package standard (load-records.js
+      // walkRecordsWithSkips, lib/safe-yaml-load.js walkDir): skip the bad
+      // repoDir instead of throwing, and name it on stderr so the operator sees
+      // WHICH directory was unreadable in CI logs rather than a raw stack.
+      for (const file of listLeafFiles(repoDir)) {
         if (extname(file) === '.yaml') {
           paths.push(resolve(repoDir, file));
         }
@@ -36,6 +47,40 @@ export function discoverFindings(rootDir) {
   return paths.sort();
 }
 
+/**
+ * List the immediate entries of a leaf repo directory, guarding the bare
+ * `readdirSync` against EACCES/ENOTDIR/transient FS errors.
+ *
+ * On error the directory is SKIPPED (returns `[]`) rather than throwing, and a
+ * structured line naming the offending path is written to stderr so the failure
+ * is operator-visible in CI logs. `discoverFindings` returns a `string[]` of
+ * paths (no structured-skip channel rides the return shape), so this mirrors
+ * the `findRecordFile` precedent (derive/load-records.js) of surfacing the skip
+ * via stderr rather than silently swallowing it — a bad directory must not sink
+ * discovery for every other repo, but it must also not vanish without a trace.
+ *
+ * Exported (package-internal) so the B002 leaf-IO guard can be exercised
+ * directly with a real, portable readdir error (readdir on a non-directory
+ * throws ENOTDIR on every platform), since the listDirs+leaf walk couples
+ * statSync and readdirSync such that the failure cannot be staged through the
+ * full walk cross-platform.
+ *
+ * @param {string} repoDir - Absolute path to a findings/<org>/<repo> directory.
+ * @returns {string[]} Entry names, or `[]` if the directory could not be read.
+ */
+export function listLeafFiles(repoDir) {
+  try {
+    return readdirSync(repoDir);
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.error(
+      `discoverFindings: skipping unreadable findings directory ${repoDir}: ${err.message}. ` +
+      `Fix the directory's permissions/state and re-run; other repos were still discovered.`
+    );
+    return [];
+  }
+}
+
 /**
  * Discover finding files from fixtures directory.
  * @param {string} rootDir - The dogfood-labs repo root.

package/review/event-log.js

@@ -26,11 +26,22 @@ export function generateEventId() {
 
 /**
  * Create a review event object.
+ *
+ * F2-INTEL-001 — back-compat extension for synthesis-artifact review events.
+ * The original event shape is keyed by `finding_id`; the synthesis-artifact
+ * review engine (review/review-artifacts.js) operates on patterns /
+ * recommendations / doctrine, which have no `finding_id`. When `params.artifactId`
+ * is supplied the event carries `artifact_id` + `artifact_kind` INSTEAD of
+ * `finding_id`, so the same append-only log and `getAllEvents` reader serve both
+ * object families. Finding events are byte-for-byte unchanged — the artifact
+ * fields are additive and only appear when `artifactId` is set.
  */
 export function createEvent(params) {
   const event = {
     review_event_id: generateEventId(),
-    finding_id: params.findingId,
+    ...(params.artifactId
+      ? { artifact_id: params.artifactId, artifact_kind: params.artifactKind }
+      : { finding_id: params.findingId }),
     timestamp: new Date().toISOString(),
     actor: params.actor,
     action: params.action,

package/review/review-artifacts.js

@@ -0,0 +1,263 @@
+/**
+ * Review engine for SYNTHESIS ARTIFACTS (patterns / recommendations / doctrine).
+ *
+ * F2-INTEL-001 — closes the intelligence loop. `synthesis/` derives patterns,
+ * recommendations, and doctrine and writes them with `status: 'candidate'`, but
+ * `advise/query.js` (`queryPatterns` / `queryRecommendations` / `queryDoctrine`)
+ * surfaces ONLY `status === 'accepted'`. At HEAD the finding review engine
+ * (`review/review-engine.js`) could promote findings, but NOTHING could promote
+ * a synthesis artifact candidate → accepted, so nothing the intelligence layer
+ * derived ever reached the advise surface. This module is the missing verb.
+ *
+ * It mirrors `performAction` (review/review-engine.js) and REUSES the finding
+ * status law verbatim (`validateTransition`, `ACTION_TARGET_STATUS`,
+ * `REASON_REQUIRED`, `REQUIRES_ACCEPTED`, `REQUIRES_CLOSED` from
+ * review/transitions.js). Persistence goes through the synthesis writers
+ * (`writePattern` / `writeRecommendation` / `writeDoctrine`), which re-validate
+ * the promoted artifact against its JSON Schema before it touches disk.
+ *
+ * Contract reality (load-bearing): the artifact schemas constrain `status` to a
+ * NARROWER set than findings —
+ *   pattern        : candidate | accepted | rejected | invalidated
+ *   recommendation : candidate | accepted | rejected
+ *   doctrine       : candidate | accepted | rejected
+ * None of them permit `reviewed`. The finding law's intermediate `reviewed`
+ * state is therefore not expressible for artifacts: actions whose
+ * `ACTION_TARGET_STATUS` is `reviewed` (`review`, `reopen`) cannot persist a
+ * schema-valid artifact, and so are refused HONESTLY with a structured error
+ * rather than writing an artifact the contract would reject. `invalidate` is the
+ * one special case the contract supports — but only for patterns, which carry a
+ * literal `invalidated` status. Recommendations and doctrine lack it, so
+ * `invalidate` on those is refused with a structured hint. This is honest
+ * partial coverage, not a silent no-op.
+ */
+
+import { validateTransition, ACTION_TARGET_STATUS, REASON_REQUIRED, REQUIRES_ACCEPTED, REQUIRES_CLOSED } from './transitions.js';
+import { createEvent, appendEvent } from './event-log.js';
+import {
+  resetSeenArtifactWrites,
+  writePattern,
+  writeRecommendation,
+  writeDoctrine,
+  loadPatternsWithSkips,
+  loadRecommendationsWithSkips,
+  loadDoctrinesWithSkips
+} from '../synthesis/write-artifacts.js';
+
+/**
+ * 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
+ * `findById` + writer; here the type is a first-class parameter.
+ */
+const ARTIFACT_TYPES = {
+  pattern: {
+    dir: 'patterns',
+    idKey: 'pattern_id',
+    loadWithSkips: loadPatternsWithSkips,
+    write: writePattern,
+    statuses: new Set(['candidate', 'accepted', 'rejected', 'invalidated']),
+    hasInvalidatedStatus: true
+  },
+  recommendation: {
+    dir: 'recommendations',
+    idKey: 'recommendation_id',
+    loadWithSkips: loadRecommendationsWithSkips,
+    write: writeRecommendation,
+    statuses: new Set(['candidate', 'accepted', 'rejected']),
+    hasInvalidatedStatus: false
+  },
+  doctrine: {
+    dir: 'doctrine',
+    idKey: 'doctrine_id',
+    loadWithSkips: loadDoctrinesWithSkips,
+    write: writeDoctrine,
+    statuses: new Set(['candidate', 'accepted', 'rejected']),
+    hasInvalidatedStatus: false
+  }
+};
+
+/**
+ * Find a single synthesis artifact by id.
+ *
+ * @param {string} rootDir
+ * @param {'pattern'|'recommendation'|'doctrine'} type
+ * @param {string} id
+ * @returns {{ data: object, path: string, type: string } | null}
+ */
+export function findArtifactById(rootDir, type, id) {
+  const cfg = ARTIFACT_TYPES[type];
+  if (!cfg) return null;
+  const { entries } = cfg.loadWithSkips(rootDir);
+  for (const entry of entries) {
+    if (entry.data && entry.data[cfg.idKey] === id) {
+      return { data: entry.data, path: entry.path, type };
+    }
+  }
+  return null;
+}
+
+/**
+ * Perform a review action on a synthesis artifact — the artifact analogue of
+ * `performAction`. Promotes a candidate to accepted (closing the loop),
+ * rejects, or invalidates per the reused finding status law.
+ *
+ * @param {string} rootDir
+ * @param {object} params
+ * @param {'pattern'|'recommendation'|'doctrine'} params.type
+ * @param {string} params.id
+ * @param {string} params.action - accept | reject | review | reopen | invalidate
+ * @param {string} params.actor
+ * @param {string} [params.reason]
+ * @param {string} [params.notes]
+ * @returns {{ success: boolean, error?: string, artifact?: object, event?: object }}
+ */
+export function reviewArtifact(rootDir, params) {
+  const { type, id, action, actor } = params;
+
+  if (!type || !ARTIFACT_TYPES[type]) {
+    return { success: false, error: `Unknown artifact type: "${type}". Expected pattern|recommendation|doctrine.` };
+  }
+  if (!id) return { success: false, error: 'id is required' };
+  if (!action) return { success: false, error: 'action is required' };
+  if (!actor) return { success: false, error: 'actor is required' };
+  if (!(action in ACTION_TARGET_STATUS)) {
+    return { success: false, error: `Unknown action: "${action}"` };
+  }
+
+  const cfg = ARTIFACT_TYPES[type];
+
+  // Load the artifact
+  const found = findArtifactById(rootDir, type, id);
+  if (!found) return { success: false, error: `${type} not found: ${id}` };
+
+  const artifact = found.data;
+  const fromStatus = artifact.status;
+
+  // Enforce reason requirement (reused REASON_REQUIRED)
+  if (REASON_REQUIRED.has(action) && !params.reason) {
+    return { success: false, error: `Action "${action}" requires a reason` };
+  }
+
+  // Enforce accepted-only actions (reused REQUIRES_ACCEPTED — invalidate)
+  if (REQUIRES_ACCEPTED.has(action) && fromStatus !== 'accepted') {
+    return { success: false, error: `Action "${action}" requires status "accepted", got "${fromStatus}"` };
+  }
+
+  // Enforce closed-only actions (reused REQUIRES_CLOSED — reopen)
+  if (REQUIRES_CLOSED.has(action) && fromStatus !== 'accepted' && fromStatus !== 'rejected') {
+    return { success: false, error: `Action "${action}" requires status "accepted" or "rejected", got "${fromStatus}"` };
+  }
+
+  // Determine the law's target status (reused ACTION_TARGET_STATUS)
+  const lawTarget = ACTION_TARGET_STATUS[action];
+
+  // Validate the transition under the reused finding law FIRST — an unlawful
+  // transition is refused with the same vocabulary the finding engine uses.
+  if (lawTarget !== null && lawTarget !== fromStatus) {
+    const transResult = validateTransition(fromStatus, lawTarget);
+    if (!transResult.valid) {
+      return { success: false, error: transResult.error };
+    }
+  }
+
+  // Map the law's target status onto the NARROWER artifact contract.
+  // The finding law uses `reviewed` as an intermediate state; artifact schemas
+  // do not permit it. Refuse honestly where the artifact cannot hold the state.
+  let toStatus;
+  if (action === 'invalidate') {
+    if (!cfg.hasInvalidatedStatus) {
+      return {
+        success: false,
+        error: `invalidate is not supported for ${type}: its schema has no "invalidated" status. ` +
+          `Use reject (with a reason) to retire an accepted ${type}.`
+      };
+    }
+    toStatus = 'invalidated';
+  } else if (lawTarget === 'reviewed') {
+    // `review` / `reopen` target the intermediate `reviewed` state, which no
+    // artifact schema permits. Refuse rather than write an invalid artifact.
+    return {
+      success: false,
+      error: `Action "${action}" targets status "reviewed", which the ${type} contract does not allow ` +
+        `(${type} status ∈ {${[...cfg.statuses].join(', ')}}). Use accept or reject instead.`
+    };
+  } else {
+    toStatus = lawTarget;
+  }
+
+  // Defensive: never persist a status the artifact schema forbids.
+  if (!cfg.statuses.has(toStatus)) {
+    return { success: false, error: `Computed status "${toStatus}" is not valid for ${type}.` };
+  }
+
+  const now = new Date().toISOString();
+
+  // Apply status + review metadata. `last_action` mirrors the finding engine's
+  // review block. For invalidate, `last_action: 'invalidate'` is what
+  // queryPatterns checks to exclude the artifact (advise/query.js).
+  artifact.status = toStatus;
+  artifact.review = {
+    reviewed_by: actor,
+    reviewed_at: now,
+    last_action: action,
+    ...(params.reason ? { decision_reason: params.reason } : {})
+  };
+  artifact.updated_at = now;
+
+  // Build the review event (carries artifact id + kind, back-compat).
+  const event = createEvent({
+    artifactId: id,
+    artifactKind: type,
+    actor,
+    action,
+    fromStatus,
+    toStatus,
+    reason: params.reason,
+    notes: params.notes
+  });
+
+  // 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).
+  try {
+    resetSeenArtifactWrites(rootDir);
+    cfg.write(rootDir, artifact);
+  } catch (err) {
+    return { success: false, error: err.message, code: err.code };
+  }
+
+  // Append the event only after the artifact persisted successfully.
+  appendEvent(rootDir, event);
+
+  return { success: true, artifact, event };
+}
+
+/**
+ * Get the artifact review queue: candidate artifacts needing operator attention.
+ * Mirrors `getReviewQueue` (review/review-engine.js). With `type` omitted,
+ * scans all three artifact families.
+ *
+ * @param {string} rootDir
+ * @param {'pattern'|'recommendation'|'doctrine'} [type]
+ * @returns {Array<{ data: object, path: string, type: string, queueReason: string }>}
+ */
+export function getArtifactReviewQueue(rootDir, type) {
+  const types = type ? [type] : Object.keys(ARTIFACT_TYPES);
+  const queue = [];
+
+  for (const t of types) {
+    const cfg = ARTIFACT_TYPES[t];
+    if (!cfg) continue;
+    const { entries } = cfg.loadWithSkips(rootDir);
+    for (const entry of entries) {
+      const data = entry.data;
+      if (!data) continue;
+      if (data.status === 'candidate') {
+        queue.push({ data, path: entry.path, type: t, queueReason: 'Unreviewed candidate' });
+      }
+    }
+  }
+
+  return queue;
+}

package/synthesis/apply-recommendation.js

@@ -0,0 +1,242 @@
+/**
+ * Apply-back for accepted recommendations (F2-INTEL-003).
+ *
+ * The intelligence layer derives recommendations whose `action` describes a
+ * concrete operational change: `{ type, target, details }` where
+ *   type   ∈ add_check | add_scenario | set_policy | set_evidence |
+ *            add_review_step | set_verification
+ *   target ≤ 100 chars
+ *   details = FREE TEXT (the human-readable intent)
+ *
+ * This module turns an ACCEPTED recommendation into an actual edit — but only
+ * where it is safe and unambiguous. Honest partial automation, never a fake
+ * auto-apply:
+ *
+ *   - Only `status === 'accepted'` is applicable. A candidate / rejected
+ *     recommendation refuses with a structured error.
+ *   - The only structurally-safe edit is adding the recommendation's `target`
+ *     (a scenario / check id) to a named repo policy's
+ *     `surfaces.<surface>.required_scenarios` list. `add_scenario` and
+ *     `add_check` map to this; every other action type is free-text-only intent
+ *     and REFUSES on --write with a hint to apply manually.
+ *   - The free-text `details` is NEVER injected into the policy as logic — it is
+ *     recorded as provenance only.
+ *   - dry-run (default) renders the proposed change and writes nothing.
+ *
+ * Structured errors all carry { code, message, hint } so the CLI and any
+ * programmatic caller see the same vocabulary.
+ *
+ * TEST_ROOT-safe: every path is derived from `rootDir`; no real-tree paths are
+ * hard-coded.
+ */
+
+import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import yaml from 'js-yaml';
+
+import { atomicWriteFileSync } from '../lib/atomic-write.js';
+import { findArtifactById } from '../review/review-artifacts.js';
+import { createEvent, appendEvent } from '../review/event-log.js';
+
+/**
+ * Action types whose `target` is a structured id we can safely add to a policy's
+ * required-scenarios list. Everything else is free-text-only intent.
+ */
+const STRUCTURED_LIST_ACTIONS = new Set(['add_scenario', 'add_check']);
+
+function structuredError(code, message, hint) {
+  return { success: false, error: { code, message, hint } };
+}
+
+/**
+ * @param {string} rootDir
+ * @param {object} params
+ * @param {string} params.id - recommendation_id
+ * @param {'dry-run'|'write'} [params.mode='dry-run']
+ * @param {string} [params.actor='operator']
+ * @param {string} [params.policyRepo] - org/repo naming the policy to edit (required for --write)
+ * @returns {{ success: boolean, applied?: boolean, preview?: object, provenance?: object, error?: { code, message, hint } }}
+ */
+export function applyRecommendation(rootDir, params) {
+  const { id } = params;
+  const mode = params.mode || 'dry-run';
+  const actor = params.actor || 'operator';
+
+  if (!id) {
+    return structuredError('RECOMMENDATION_ID_REQUIRED', 'id is required', 'Pass the recommendation_id to apply.');
+  }
+
+  // Load the recommendation.
+  const found = findArtifactById(rootDir, 'recommendation', id);
+  if (!found) {
+    return structuredError(
+      'RECOMMENDATION_NOT_FOUND',
+      `recommendation not found: ${id}`,
+      'Run `findings recommendations list` to see available ids.'
+    );
+  }
+  const rec = found.data;
+
+  // Applicability gate — only accepted recommendations are applicable.
+  if (rec.status !== 'accepted') {
+    return structuredError(
+      'RECOMMENDATION_NOT_ACCEPTED',
+      `recommendation ${id} has status "${rec.status}" — only accepted recommendations can be applied`,
+      'Accept it first: `findings recommendations accept ' + id + ' --actor <name>`.'
+    );
+  }
+
+  const action = rec.action || {};
+  const surfaces = rec.applies_to?.product_surfaces || [];
+
+  // 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;
+
+  // ── dry-run: render the proposed change, write nothing ──────────────
+  if (mode !== 'write') {
+    const policyPath = params.policyRepo ? policyPathFor(rootDir, params.policyRepo) : null;
+    return {
+      success: true,
+      applied: false,
+      preview: {
+        recommendationId: id,
+        actionType: action.type,
+        target: action.target,
+        details: action.details,
+        surface: surface,
+        surfaces,
+        autoApplicable: isStructured && !!surface,
+        policyRepo: params.policyRepo || null,
+        policyPath: policyPath,
+        field: isStructured ? `surfaces.${surface || '<surface>'}.required_scenarios` : null,
+        note: isStructured
+          ? (surface
+            ? `Would add "${action.target}" to required_scenarios for surface "${surface}". Free-text details recorded as provenance only.`
+            : `Action is structurally applicable but the recommendation spans ${surfaces.length} surface(s); --write needs a single surface.`)
+          : `Action type "${action.type}" is free-text-only intent — review the details and apply manually. --write will refuse.`
+      }
+    };
+  }
+
+  // ── write: apply ONLY the safe, unambiguous structured intent ───────
+
+  // Free-text-only intent (set_policy / set_evidence / set_verification /
+  // add_review_step) cannot be safely auto-applied.
+  if (!isStructured) {
+    return structuredError(
+      'RECOMMENDATION_NOT_AUTO_APPLICABLE',
+      `recommendation ${id} action type "${action.type}" carries free-text-only intent`,
+      `The intent lives in action.details, which must not be injected as policy logic. Apply manually: "${action.details}".`
+    );
+  }
+
+  // Need a named policy to edit.
+  if (!params.policyRepo) {
+    return structuredError(
+      'RECOMMENDATION_AMBIGUOUS_TARGET',
+      `recommendation ${id} does not name a policy to edit`,
+      'Pass --policy <org/repo> to name the repo policy whose required_scenarios should gain "' + action.target + '".'
+    );
+  }
+
+  // Need an unambiguous surface.
+  if (!surface) {
+    return structuredError(
+      'RECOMMENDATION_AMBIGUOUS_TARGET',
+      `recommendation ${id} applies to ${surfaces.length} surface(s) — cannot pick one automatically`,
+      'Narrow the recommendation to a single product_surface, then re-run, or edit the policy manually.'
+    );
+  }
+
+  if (!action.target) {
+    return structuredError(
+      'RECOMMENDATION_AMBIGUOUS_TARGET',
+      `recommendation ${id} has no action.target id to add`,
+      'A structured add_scenario/add_check action must carry a target id. Apply manually.'
+    );
+  }
+
+  // Load the named policy.
+  const policyPath = policyPathFor(rootDir, params.policyRepo);
+  if (!existsSync(policyPath)) {
+    return structuredError(
+      'RECOMMENDATION_TARGET_POLICY_MISSING',
+      `policy not found for ${params.policyRepo} at ${policyPath}`,
+      'Create the repo policy first, or pass a --policy that exists.'
+    );
+  }
+
+  let policy;
+  try {
+    policy = yaml.load(readFileSync(policyPath, 'utf-8')) || {};
+  } catch (err) {
+    return structuredError(
+      'RECOMMENDATION_TARGET_POLICY_UNREADABLE',
+      `could not parse policy ${params.policyRepo}: ${err.message}`,
+      'Fix the policy YAML, then re-run.'
+    );
+  }
+
+  // Apply the structured intent: add target to surfaces.<surface>.required_scenarios.
+  if (!policy.surfaces) policy.surfaces = {};
+  if (!policy.surfaces[surface]) policy.surfaces[surface] = {};
+  if (!Array.isArray(policy.surfaces[surface].required_scenarios)) {
+    policy.surfaces[surface].required_scenarios = [];
+  }
+  const list = policy.surfaces[surface].required_scenarios;
+  const alreadyPresent = list.includes(action.target);
+  if (!alreadyPresent) list.push(action.target);
+
+  // Record provenance — recommendation_id + (free-text) details, kept OUT of any
+  // logic field. Stored under a dedicated `applied_recommendations` map keyed by
+  // the scenario id so it is auditable but never interpreted by the policy
+  // engine. The free-text details live here as a human note, never as a rule.
+  if (!policy.applied_recommendations) policy.applied_recommendations = {};
+  const provenance = {
+    recommendation_id: id,
+    action_type: action.type,
+    target: action.target,
+    surface,
+    details: action.details,
+    applied_by: actor,
+    applied_at: new Date().toISOString()
+  };
+  policy.applied_recommendations[action.target] = provenance;
+
+  // NOTE: provenance is intentionally written under a NON-schema key. The policy
+  // schema (`policy.schema.json`) has `additionalProperties: false`, so a real
+  // policy would reject `applied_recommendations`. We keep the provenance OUT of
+  // the validated surface by returning it on the result for the operator and the
+  // event log, and we strip it before persisting so the policy stays schema-valid.
+  const persistable = { ...policy };
+  delete persistable.applied_recommendations;
+
+  atomicWriteFileSync(policyPath, yaml.dump(persistable, { lineWidth: 120, noRefs: true }));
+
+  // Log an apply event (recommendation review-event shape; action 'apply').
+  const event = createEvent({
+    artifactId: id,
+    artifactKind: 'recommendation',
+    actor,
+    action: 'apply',
+    fromStatus: 'accepted',
+    toStatus: 'accepted',
+    notes: `Applied ${action.type} target=${action.target} to ${params.policyRepo} surface=${surface}`
+  });
+  appendEvent(rootDir, event);
+
+  return {
+    success: true,
+    applied: true,
+    alreadyPresent,
+    policyPath,
+    provenance
+  };
+}
+
+/** Resolve the on-disk path for a repo policy under rootDir. */
+function policyPathFor(rootDir, orgRepo) {
+  const [org, repo] = orgRepo.split('/');
+  return resolve(rootDir, 'policies', 'repos', org, `${repo}.yaml`);
+}

package/synthesis/dedupe-artifacts.js

@@ -0,0 +1,67 @@
+/**
+ * Deduplication for derived synthesis-artifact candidates (patterns /
+ * recommendations / doctrine).
+ *
+ * F2-INTEL-002 — the artifact analogue of `derive/dedupe.js`
+ * `dedupeAgainstExisting`. Re-running `findings <type> derive --write` produces
+ * the SAME deterministic ids as the prior run. At HEAD the writers would
+ * silently overwrite the on-disk file via `atomicWriteFileSync`, so an artifact
+ * the operator had already accepted / rejected / invalidated would be reset to a
+ * fresh `candidate` — erasing the operator's decision and re-breaking the loop
+ * that F2-INTEL-001 closed.
+ *
+ * Dedupe law (identical to the findings dedupe semantics):
+ *   - id not on disk            → write (new artifact)
+ *   - id on disk, status candidate → write (refresh the machine output)
+ *   - id on disk, NON-candidate status (reviewed/accepted/rejected/invalidated)
+ *                                → COLLISION, do NOT overwrite. The operator's
+ *                                  decision is load-bearing and survives.
+ *
+ * The decision is intentionally the conservative one the findings layer already
+ * makes: preserve the operator's status by skipping the re-write entirely. The
+ * refreshed machine content is discarded for a promoted artifact rather than
+ * merged, because merging fresh `candidate`-shaped content into an `accepted`
+ * artifact would silently mutate what the operator signed off on.
+ */
+
+/**
+ * @param {Array<object>} candidates - Freshly-derived artifact candidates.
+ * @param {Array<{ data: object }>} existing - Already-loaded on-disk artifacts
+ *   (e.g. `loadPatternsWithSkips(rootDir).entries`).
+ * @param {string} idKey - The artifact's id field ('pattern_id' |
+ *   'recommendation_id' | 'doctrine_id').
+ * @returns {{ toWrite: Array<object>, skippedUnchanged: number, collisions: Array<{ id: string, existingStatus: string }> }}
+ */
+export function dedupeArtifactsAgainstExisting(candidates, existing, idKey) {
+  const existingById = new Map();
+  for (const e of existing || []) {
+    const data = e?.data;
+    if (data && data[idKey]) existingById.set(data[idKey], data);
+  }
+
+  const toWrite = [];
+  let skippedUnchanged = 0;
+  const collisions = [];
+
+  for (const c of candidates) {
+    const id = c?.[idKey];
+    const prior = id != null ? existingById.get(id) : undefined;
+
+    if (!prior) {
+      toWrite.push(c);
+      continue;
+    }
+
+    // Same id exists — the operator's status is the gate.
+    if (prior.status !== 'candidate') {
+      // Promoted artifact: collision, never overwrite.
+      collisions.push({ id, existingStatus: prior.status });
+      continue;
+    }
+
+    // Still a candidate on disk — refresh the machine output.
+    toWrite.push(c);
+  }
+
+  return { toWrite, skippedUnchanged, collisions };
+}

package/synthesis/index.js

@@ -8,5 +8,8 @@ export { validatePattern, validateRecommendation, validateDoctrine } from './val
 export {
   writePattern, writeRecommendation, writeDoctrine,
   writePatterns, writeRecommendations, writeDoctrines,
-  loadPatterns, loadRecommendations, loadDoctrines
+  loadPatterns, loadRecommendations, loadDoctrines,
+  loadPatternsWithSkips, loadRecommendationsWithSkips, loadDoctrinesWithSkips,
+  resetSeenArtifactWrites
 } from './write-artifacts.js';
+export { dedupeArtifactsAgainstExisting } from './dedupe-artifacts.js';

package/synthesis/pattern-derivation.js

@@ -12,9 +12,20 @@ import { loadFindings } from '../reader.js';
 /**
  * Derive candidate patterns from accepted findings.
  *
+ * D2B-001 — return shape carries a `skipped: [{ path, error }]` field so the
+ * silent-loader signal that the recommendation/doctrine derive stages already
+ * surface now also propagates through pattern derivation. `loadFindings`
+ * (reader.js) returns a torn / unparseable finding YAML as
+ * `{ valid: false, errors: [{ message }] }`; a torn file that on disk WAS an
+ * accepted finding would otherwise be filtered out of clustering with zero
+ * operator signal, quietly shrinking the evidence base behind a pattern's
+ * strength or threshold. The `skipped` list documents that partial-completion
+ * honestly. Legacy callers reading only `patterns` / `stats` are unaffected —
+ * the field is additive.
+ *
  * @param {string} rootDir - dogfood-labs repo root
  * @param {{ includeFixtures?: boolean }} opts
- * @returns {{ patterns: Array, stats: { findingsConsidered: number, clustersFound: number, belowThreshold: number } }}
+ * @returns {{ patterns: Array, skipped: Array<{path: string, error: string}>, stats: { findingsConsidered: number, clustersFound: number, belowThreshold: number, findingsSkipped: number } }}
  */
 export function derivePatterns(rootDir, opts = {}) {
   // Load only accepted, non-invalidated findings
@@ -23,6 +34,15 @@ export function derivePatterns(rootDir, opts = {}) {
     allFindings.push(...loadFindings(rootDir, { fixtures: true, fixtureKind: 'valid' }));
   }
 
+  // D2B-001 — partition torn / unreadable findings into a structured skip list
+  // BEFORE the accepted filter drops them. A `valid:false` record is a finding
+  // YAML that failed parse (reader.js sets errors[0].message to the parse error)
+  // or schema validation; its on-disk status is unknowable, so a torn file that
+  // WAS an accepted finding must not vanish silently from clustering.
+  const skipped = allFindings
+    .filter(f => f.valid === false)
+    .map(f => ({ path: f.path, error: f.errors?.[0]?.message || 'unknown read/parse error' }));
+
   const accepted = allFindings.filter(f =>
     f.valid &&
     f.data?.status === 'accepted' &&
@@ -68,10 +88,12 @@ export function derivePatterns(rootDir, opts = {}) {
 
   return {
     patterns,
+    skipped, // D2B-001: structured skip list for operator legibility
     stats: {
       findingsConsidered: accepted.length,
       clustersFound: clusters.size,
-      belowThreshold
+      belowThreshold,
+      findingsSkipped: skipped.length
     }
   };
 }