@dogfood-lab/findings 1.3.2 → 1.5.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,41 @@ 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
+
+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
+  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 +299,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 +749,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 +790,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 +814,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 +853,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 +910,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 +934,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 +956,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 +992,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 +1027,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 +1049,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 +1084,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);
   }
 
@@ -890,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.3.2",
+  "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",
@@ -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",