@dogfood-lab/findings 1.4.0 → 1.5.0

package/cli.js

@@ -279,6 +279,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
@@ -1095,6 +1103,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/findings",
-  "version": "1.4.0",
+  "version": "1.5.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,13 +152,26 @@ 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;
 }
 

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/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/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'