@dogfood-lab/findings 1.9.0 → 1.10.0

package/advise/query.js

@@ -113,6 +113,26 @@ export function queryRecommendations(rootDir, scope = {}) {
 
 /**
  * Query accepted doctrine by scope.
+ *
+ * F-d022c023: the surface-scoping filter below used to end in a bare `true`
+ * — since doctrine.transfer_scope is a closed 3-value enum
+ * (packages/schemas/src/json/dogfood-doctrine.schema.json: org_wide,
+ * execution_mode, surface_archetype) and the first two branches already
+ * matched two of the three values explicitly, the trailing `true` made the
+ * WHOLE expression unconditionally true for every doctrine record — a
+ * structural no-op covering 100% of the enum, not a rare edge case.
+ * Replacing that `true` with a third literal `transfer_scope ===
+ * 'surface_archetype'` comparison would be an equally-complete no-op (the
+ * three literal branches would still exhaust the closed enum and always be
+ * true) — so it does NOT satisfy this fix; it would just move the dead code
+ * one line over. doctrine itself carries NO per-record surface field to
+ * compare against (the schema's `additionalProperties: false` rules one out
+ * without a schema/version bump), so a REAL surface_archetype check has to
+ * reach through `based_on_pattern_ids` to the patterns' own
+ * `dimensions.product_surfaces` — the same signal `queryPatterns` above
+ * already uses, and the literal thing this function's own (correct) comment
+ * about org_wide/execution_mode always says: "surface_archetype applies if
+ * pattern surfaces match."
  */
 export function queryDoctrine(rootDir, scope = {}) {
   const all = loadDoctrines(rootDir);
@@ -121,13 +141,22 @@ export function queryDoctrine(rootDir, scope = {}) {
   let results = all.filter(d => d.status === 'accepted');
 
   if (scope.surface) {
-    // Doctrine applies if its scope is broad enough or matches the surface
-    // org_wide always applies; surface_archetype applies if pattern surfaces match
-    results = results.filter(d =>
-      d.transfer_scope === 'org_wide' ||
-      d.transfer_scope === 'execution_mode' ||
-      true // surface_archetype applies broadly — patterns already scoped it
+    // org_wide and execution_mode are surface-agnostic BY DEFINITION (their
+    // whole point is applying beyond any single surface), so they always
+    // pass once ANY surface is requested — that part of the original intent
+    // was correct and is unchanged. surface_archetype is the one scope tied
+    // to a specific surface lineage: does the requested surface appear in
+    // the dimensions.product_surfaces of AT LEAST ONE pattern this doctrine
+    // is based_on_pattern_ids-derived from?
+    const patternSurfacesById = new Map(
+      loadPatterns(rootDir).map(p => [p.pattern_id, p.dimensions?.product_surfaces || []])
     );
+    results = results.filter(d => {
+      if (d.transfer_scope === 'org_wide' || d.transfer_scope === 'execution_mode') return true;
+      return (d.based_on_pattern_ids || []).some(
+        pid => patternSurfacesById.get(pid)?.includes(scope.surface)
+      );
+    });
   }
 
   results.sort((a, b) => {

package/derive/ids.js

@@ -38,17 +38,35 @@ export function generateFindingId(repoSlug, lessonSlug) {
  * Compute a dedupe key for collision detection.
  * Two findings with the same dedupe key are considered the same lesson.
  *
+ * F-112c88a4: defense-in-depth sibling of generateFindingId's own
+ * boundary-collision fix (findings-A-002, above). A plain `'::'.join()` here
+ * would let a delimiter-shaped VALUE in one field forge a false boundary
+ * with its neighbor — e.g. (issue_kind='x::y', root_cause_kind='z') and
+ * (issue_kind='x', root_cause_kind='y::z') both flatten to the same joined
+ * string. Routed through the same NUL-delimited boundaryHash() helper
+ * generateFindingId uses, so no component value can forge a boundary
+ * regardless of what it contains.
+ *
+ * Today's five fields are each enum- or pattern-constrained upstream (see
+ * dogfood-finding.schema.json) such that none can actually contain '::', so
+ * this specific collision is not reachable through the intended pipeline —
+ * but that safety lives entirely in the CALLER's schema, not in this
+ * function's own construction. boundaryHash() makes computeDedupeKey safe on
+ * its own terms, so a future caller (or a future schema relaxation on any of
+ * these fields) cannot unknowingly reopen the collision generateFindingId
+ * was explicitly fixed to close.
+ *
  * @param {{ repo: string, issue_kind: string, root_cause_kind: string, journey_stage: string, slug: string }} fields
  * @returns {string}
  */
 export function computeDedupeKey(fields) {
-  return [
+  return boundaryHash([
     fields.repo,
     fields.issue_kind,
     fields.root_cause_kind,
     fields.journey_stage,
     fields.slug
-  ].join('::');
+  ]);
 }
 
 /**

package/derive/load-records.js

@@ -33,7 +33,17 @@ export function loadRecordsForRepo(rootDir, repoKey) {
  * @returns {{ entries: Array<{ record: object, rejected: boolean, path: string }>, skipped: Array<{ path: string, error: string }> }}
  */
 export function loadRecordsForRepoWithSkips(rootDir, repoKey) {
-  const [org, repo] = repoKey.split('/');
+  // F-60a31e29: two-segment contract (F-916867-005 family) — mirrors
+  // persist.js:51 and load-context.js:138/333, which both enforce
+  // `segments.length !== 2` ahead of the traversal guard below. This site
+  // was the odd one out: a bare 2-way destructure silently DROPPED any
+  // third segment, so `loadRecordsForRepoWithSkips(root, 'a/b/c')` silently
+  // loaded records for the DIFFERENT repo 'a/b' instead of failing closed.
+  const segments = repoKey.split('/');
+  if (segments.length !== 2) {
+    return { entries: [], skipped: [] };
+  }
+  const [org, repo] = segments;
   // Path-traversal guard: F-916867-005. Mirrors persist.js + load-context.js
   // via the central helper at @dogfood-lab/ingest/lib/unsafe-segment.js.
   // A malformed repoKey (`..` or path-separator) would otherwise resolve

package/derive/rules.js

@@ -13,6 +13,21 @@
  *   repoSlug  — e.g. "repo-crawler-mcp"
  */
 
+// F-e1d45d27 (wave 12, LOW): ruleSchemaRejection/rulePolicyRejection below used
+// to hand-roll `/^schema:/` / `/^policy:/` against raw rejection_reasons
+// strings — exactly the drift parse-rejection.js's own file header exists to
+// end ("every operator discriminated failure class with hand-rolled
+// .startsWith() chains ... a fresh drift source the moment a prefix is
+// added"). `@dogfood-lab/verify` was already a TRANSITIVE dependency here (via
+// @dogfood-lab/ingest) and depends on nothing beyond @dogfood-lab/schemas +
+// js-yaml, so importing it directly adds no new workspace cycle. Routing
+// through the authoritative classifier (`.prefix === 'schema:'` / `'policy:'`)
+// is behaviorally identical today — see derive.test.js's "Regression: rules.js
+// schema:/policy: routes through parseRejectionReason (F-e1d45d27)" describe
+// block for the differential proof — and stays correct automatically if the
+// taxonomy ever grows or reorders.
+import { parseRejectionReason } from '@dogfood-lab/verify';
+
 // ─── Helpers ────────────────────────────────────────────────
 
 function hasRejectionMatching(record, pattern) {
@@ -46,6 +61,33 @@ function scenarioVerdict(record) {
   return record.scenario_results?.[0]?.verdict || null;
 }
 
+// F-88fb37ff: a scenario's step_results is the ONLY corroborating evidence
+// for a self-reported "blocked" (or "fail") verdict — a verifier fix closed
+// this same gap in @dogfood-lab/verify's validateStepResults, but the derive
+// pipeline reads records from BOTH records/ and records/_rejected/ (see
+// load-records.js) and never consults verification.status, so a
+// self-contradictory record still reaches every rule here with
+// scenario_results untouched. ruleScenarioStepFailure already gates on
+// failedSteps(record).length > 0 for the "fail" verdict; this mirrors that
+// same evidentiary floor for a single scenario object (rule-blocked-scenario
+// iterates scenarios directly rather than through the record-level,
+// index-0-only helpers above).
+//
+// F-e42e8f80 (wave 20, amends F-88fb37ff): renamed from hasFailOrBlockedStep
+// and its condition widened — the original "at least one step actively
+// fail/blocked" bar had the identical blind spot the verifier-level fix
+// (validateStepResults/validateRequiredSteps) closed: a genuinely blocked
+// scenario whose steps honestly report 'skip' (never ran) has ZERO
+// fail/blocked steps, so the old bar silently dropped the
+// 'verification_gap'/'missing_precondition' finding for exactly the class of
+// record most likely to deserve it. Only an ACTIVE 'pass' is a contradiction
+// of a blocked verdict; 'skip'/'partial' are neutral, like a step that never
+// ran. Mirrors the verifier-level fix's "not all pass" bar exactly.
+function hasNonPassStepEvidence(scenario) {
+  const results = scenario.step_results || [];
+  return results.some(s => s != null && s.status !== 'pass');
+}
+
 // ─── Rule 1: Surface/interface misclassification ────────────
 
 const ruleSurfaceMisclassification = {
@@ -228,7 +270,7 @@ const ruleScenarioStepFailure = {
       transfer_scope: 'surface_local',
       journey_stage: 'first_run',
       product_surface: surface,
-      slug: `${repoSlug}-step-failure-${stepIds[0]}`,
+      slug: `${repoSlug}-step-failure-${sid}-${stepIds[0]}`,
       title: `Scenario step(s) failed: ${stepIds.join(', ')} — ${surface} entrypoint or build output may be wrong`,
       summary: `The scenario failed at step(s): ${stepIds.join(', ')}. This typically indicates the entrypoint, build output path, or invocation contract differs from what the scenario expected. The scenario or build configuration needs correction.`,
       rationale: `scenario_results[0].verdict is "fail" with ${failed.length} failed step(s): ${stepIds.join(', ')}.`,
@@ -247,12 +289,16 @@ const ruleBlockedScenario = {
   description: 'Detects scenarios that were blocked entirely, typically indicating a missing precondition or infrastructure gap.',
 
   applies(ctx) {
-    return ctx.record.scenario_results?.some(s => s.verdict === 'blocked');
+    // F-88fb37ff: require step evidence backing the self-reported verdict —
+    // otherwise a self-contradictory record (blocked verdict, every step
+    // reports pass) synthesizes a plausible-sounding but false
+    // "infrastructure gap" finding the record's own evidence contradicts.
+    return ctx.record.scenario_results?.some(s => s.verdict === 'blocked' && hasNonPassStepEvidence(s));
   },
 
   derive(ctx) {
     const { record, repoSlug } = ctx;
-    const blocked = record.scenario_results.filter(s => s.verdict === 'blocked');
+    const blocked = record.scenario_results.filter(s => s.verdict === 'blocked' && hasNonPassStepEvidence(s));
 
     return blocked.map(scenario => {
       const reason = scenario.blocking_reason || 'No blocking reason provided';
@@ -330,13 +376,13 @@ const ruleSchemaRejection = {
     // Only fire if not already covered by surface misclassification
     const reasons = ctx.record.verification?.rejection_reasons || [];
     const hasSurfaceIssue = reasons.some(r => /product_surface/.test(r));
-    const hasSchemaIssue = reasons.some(r => /^schema:/.test(r));
+    const hasSchemaIssue = reasons.some(r => parseRejectionReason(r).prefix === 'schema:');
     return hasSchemaIssue && !hasSurfaceIssue;
   },
 
   derive(ctx) {
     const { record, repoSlug } = ctx;
-    const reasons = record.verification?.rejection_reasons?.filter(r => /^schema:/.test(r)) || [];
+    const reasons = record.verification?.rejection_reasons?.filter(r => parseRejectionReason(r).prefix === 'schema:') || [];
     const surface = safeRecordSurface(record, repoSlug);
 
     return [{
@@ -369,13 +415,13 @@ const rulePolicyRejection = {
     // Only fire if not already covered by evidence policy mismatch
     const reasons = ctx.record.verification?.rejection_reasons || [];
     const hasEvidenceIssue = reasons.some(r => /evidence/.test(r));
-    const hasPolicyIssue = reasons.some(r => /^policy:/.test(r));
+    const hasPolicyIssue = reasons.some(r => parseRejectionReason(r).prefix === 'policy:');
     return hasPolicyIssue && !hasEvidenceIssue;
   },
 
   derive(ctx) {
     const { record, repoSlug } = ctx;
-    const reasons = record.verification?.rejection_reasons?.filter(r => /^policy:/.test(r)) || [];
+    const reasons = record.verification?.rejection_reasons?.filter(r => parseRejectionReason(r).prefix === 'policy:') || [];
     const surface = safeRecordSurface(record, repoSlug);
 
     return [{
@@ -397,6 +443,66 @@ const rulePolicyRejection = {
   }
 };
 
+// ─── Rule 9: Partial scenario with contradicting evidence ───
+
+const rulePartialScenarioEvidence = {
+  ruleId: 'rule-partial-scenario-evidence',
+  description: 'Detects scenarios with a self-reported "partial" verdict backed by non-pass step evidence — the derivation-layer half of the F-cc198701 fix, so a partial verdict is no longer invisible to every rule in this file.',
+
+  applies(ctx) {
+    // F-cc198701 (wave 22, confirming audit of F-88fb37ff/F-e42e8f80): this
+    // rule's two closest siblings each enumerate exactly ONE of the four
+    // legal scenario_results[].verdict enum values (dogfood-record-
+    // submission.schema.json: ["pass","fail","blocked","partial"]) —
+    // ruleBlockedScenario checks only 'blocked' (line ~296 above) and
+    // ruleScenarioStepFailure checks only 'fail' (line ~240 above). Neither
+    // ever checks 'partial', so a 'partial'-verdict scenario_result was
+    // invisible to EVERY rule in this file regardless of its step evidence:
+    // a self-contradictory record (verdict:'partial' with every step actively
+    // 'fail' — strictly worse evidence than what the other two rules already
+    // catch) generated zero corrective/diagnostic finding anywhere in the
+    // intelligence layer, on top of being a false-rejection gap at the
+    // verifier layer (see steps.js's matching F-cc198701 fix, same wave).
+    //
+    // A dedicated sibling rule — rather than widening ruleBlockedScenario's
+    // own condition, which the finding's fix note offered as an alternative —
+    // keeps that rule's "was blocked: <reason>" title/summary text honest:
+    // blocking_reason is schema-documented as "Required when verdict is
+    // blocked," so reusing 'blocked' wording for a genuinely 'partial'
+    // scenario would misdescribe it to a human reviewer.
+    return ctx.record.scenario_results?.some(s => s.verdict === 'partial' && hasNonPassStepEvidence(s));
+  },
+
+  derive(ctx) {
+    const { record, repoSlug } = ctx;
+    const partial = record.scenario_results.filter(s => s.verdict === 'partial' && hasNonPassStepEvidence(s));
+
+    return partial.map(scenario => {
+      const surface = mapToValidSurface(scenario.product_surface || 'cli', repoSlug);
+      const nonPassIds = (scenario.step_results || [])
+        .filter(s => s != null && s.status !== 'pass')
+        .map(s => s.step_id);
+
+      return {
+        issue_kind: 'verification_gap',
+        root_cause_kind: 'contract_drift',
+        remediation_kind: 'scenario_change',
+        transfer_scope: 'surface_local',
+        journey_stage: 'verification',
+        product_surface: surface,
+        slug: `${repoSlug}-partial-${scenario.scenario_id}`,
+        title: `Scenario "${scenario.scenario_id}" reported "partial" backed by non-pass step evidence`,
+        summary: `The scenario "${scenario.scenario_id}" self-reported a "partial" verdict, corroborated by non-pass step(s): ${nonPassIds.join(', ')}. A partial verdict backed by non-pass evidence may indicate an incomplete run, a scenario whose success criteria need review, or a genuinely partial pass worth surfacing to the portfolio layer.`,
+        rationale: `scenario_results contains a scenario with verdict "partial" and non-pass step evidence: [${nonPassIds.join(', ')}].`,
+        evidence: [
+          { evidence_kind: 'scenario_result', record_id: record.run_id, scenario_id: scenario.scenario_id, note: `Partial verdict corroborated by non-pass steps: ${nonPassIds.join(', ')}` },
+          { evidence_kind: 'record', record_id: record.run_id, note: 'Scenario verdict is partial with corroborating non-pass step evidence.' }
+        ]
+      };
+    });
+  }
+};
+
 // ─── Export all rules ───────────────────────────────────────
 
 export const RULES = [
@@ -407,7 +513,8 @@ export const RULES = [
   ruleBlockedScenario,
   ruleExecutionModeGap,
   ruleSchemaRejection,
-  rulePolicyRejection
+  rulePolicyRejection,
+  rulePartialScenarioEvidence
 ];
 
 export function getRuleById(ruleId) {

package/lib/file-lock.js

@@ -134,10 +134,11 @@ function atomicCreateLock(lockPath) {
 }
 
 /**
- * Attempt to acquire an exclusive file-lock on `lockPath`. Returns true if
- * the lock was acquired; false if it is held by another live process OR
- * by a process whose lock file is unreadable / pid-empty (treated as live
- * with bounded mtime patience — see below).
+ * Attempt to acquire an exclusive file-lock on `lockPath`. Returns
+ * `{ acquired: true }` if the lock was acquired; `{ acquired: false, reason }`
+ * if it is held by another live process OR by a process whose lock file is
+ * unreadable / pid-empty (treated as live with bounded mtime patience — see
+ * below).
  *
  * Stale recovery: a holder's PID file remains until its release `unlink`
  * runs. If the holder PROCESS is gone (process.kill ESRCH), the lock is
@@ -149,14 +150,23 @@ function atomicCreateLock(lockPath) {
  * safer guard: we only reclaim if the lock file is ALSO older than
  * `staleAfterMs`, the same boundary `proper-lockfile` uses.
  *
+ * F-3a7c4d67: `reason` is threaded all the way out to `withFileLock`'s
+ * ELOCKTIMEOUT error message (the `lastErrCtx` variable there was declared
+ * and read but never assigned anywhere — confirmed by grep before this fix:
+ * exactly two occurrences of the identifier in the whole file, declaration +
+ * the dead read). Every real lock-timeout previously rendered the bare
+ * "timed out after Nms waiting for X" with the promised "(last error: ...)"
+ * clause permanently absent.
+ *
  * @param {string} lockPath
  * @param {{ staleAfterMs?: number }} opts
- * @returns {boolean}
+ * @returns {{ acquired: boolean, reason?: string }} `reason` is present only
+ *   when `acquired` is false.
  */
 function tryAcquire(lockPath, opts = {}) {
   const { staleAfterMs = DEFAULT_STALE_AFTER_MS } = opts;
 
-  if (atomicCreateLock(lockPath)) return true;
+  if (atomicCreateLock(lockPath)) return { acquired: true };
 
   // Lock exists — test for staleness.
   let pidRaw = null;
@@ -175,7 +185,9 @@ function tryAcquire(lockPath, opts = {}) {
   // PID-known case: trust process.kill to decide alive-vs-dead. This is the
   // common case and gives fast crash recovery (sub-100ms typical).
   if (pidRaw && pidRaw !== '') {
-    if (isProcessAlive(pidRaw)) return false;
+    if (isProcessAlive(pidRaw)) {
+      return { acquired: false, reason: `held by live process pid=${pidRaw}` };
+    }
 
     // PID-dead reclaim via "rename to graveyard" — atomic claim that exactly
     // one reclaimer wins. Without this, a sequence like:
@@ -208,7 +220,10 @@ function tryAcquire(lockPath, opts = {}) {
   }
 
   // Treat as live; the holder owns the lock and will release it.
-  return false;
+  return {
+    acquired: false,
+    reason: `lock file present with no readable pid; age below staleAfterMs=${staleAfterMs}ms`,
+  };
 }
 
 /**
@@ -232,7 +247,10 @@ function release(lockPath) {
  *
  * @param {string} lockPath
  * @param {string} expectedDeadPid - The PID we observed and confirmed dead.
- * @returns {boolean}
+ * @returns {{ acquired: boolean, reason?: string }} F-3a7c4d67: mirrors
+ *   tryAcquire's return shape so the caller can thread a real cause into
+ *   withFileLock's ELOCKTIMEOUT message instead of a permanently-null
+ *   lastErrCtx.
  */
 function reclaimViaGraveyard(lockPath, expectedDeadPid) {
   const graveyardPath = `${lockPath}.gy.${process.pid}.${randomBytes(4).toString('hex')}`;
@@ -240,7 +258,7 @@ function reclaimViaGraveyard(lockPath, expectedDeadPid) {
     renameSync(lockPath, graveyardPath);
   } catch (err) {
     // Another reclaimer beat us — let the retry loop sort it out.
-    return false;
+    return { acquired: false, reason: `stale-reclaim raced: another process already renamed ${lockPath} first` };
   }
 
   // We won the rename. Verify content.
@@ -262,7 +280,7 @@ function reclaimViaGraveyard(lockPath, expectedDeadPid) {
     } catch {
       try { unlinkSync(graveyardPath); } catch { /* drop */ }
     }
-    return false;
+    return { acquired: false, reason: `stale-reclaim raced: lock was freshly re-acquired by pid=${actualPid} during reclaim` };
   }
 
   if (process.env.FILE_LOCK_DEBUG) {
@@ -270,7 +288,9 @@ function reclaimViaGraveyard(lockPath, expectedDeadPid) {
   }
 
   try { unlinkSync(graveyardPath); } catch { /* drop */ }
-  return atomicCreateLock(lockPath);
+  return atomicCreateLock(lockPath)
+    ? { acquired: true }
+    : { acquired: false, reason: 'stale-reclaim raced: a fresh lock was created immediately after graveyard cleanup' };
 }
 
 /**
@@ -281,9 +301,23 @@ function reclaimViaGraveyard(lockPath, expectedDeadPid) {
  * cascade through six callers and break the back-compat contract on
  * `appendEvent` that review-engine relies on.
  *
+ * F-3a7c4d67: guards its documented sibling `packages/ingest/lib/sleep-
+ * sync.js` already carries ("we don't trust caller arithmetic to never
+ * produce negative deltas if a system clock skews") were missing HERE.
+ * Independently re-confirmed empirically (isolated Node one-liner, no
+ * repo writes): `Atomics.wait(view, 0, 0, NaN)` never returns — it hangs
+ * the calling thread indefinitely, with no bound, no error, no log line,
+ * the worst possible outcome for a bounded-retry primitive. A negative
+ * value, by contrast, correctly clamps to an instant 'timed-out'. Reachable
+ * via `withFileLock(path, fn, { retryIntervalMs: NaN })` — e.g. a config
+ * value computed as `x / y` with `y === 0`, or `Number(process.env.X)` on
+ * an unset var — because the destructuring default on `retryIntervalMs`
+ * below only applies when the option is `undefined`, never when it is NaN.
+ *
  * @param {number} ms
  */
 function sleepSync(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return;
   const sab = new SharedArrayBuffer(4);
   const view = new Int32Array(sab);
   Atomics.wait(view, 0, 0, ms);
@@ -326,10 +360,15 @@ export function withFileLock(targetPath, fn, options = {}) {
   let lastErrCtx = null;
 
   while (Date.now() < deadline) {
-    if (tryAcquire(lockPath, { staleAfterMs })) {
+    // F-3a7c4d67: tryAcquire now returns { acquired, reason } instead of a
+    // bare boolean specifically so lastErrCtx below stops being permanently
+    // null — see tryAcquire's own doc block for the full defect history.
+    const attempt = tryAcquire(lockPath, { staleAfterMs });
+    if (attempt.acquired) {
       acquired = true;
       break;
     }
+    if (attempt.reason) lastErrCtx = attempt.reason;
     sleepSync(retryIntervalMs);
   }
 

package/lib/rename-with-retry.js

@@ -35,21 +35,46 @@ import { renameSync } from 'node:fs';
 /**
  * Sleep synchronously for `ms` milliseconds via `Atomics.wait` on a tiny
  * SharedArrayBuffer. Yields the thread (does not spin). Mirrors the
- * `sleepSync` in `file-lock.js:286` — the contract is identical; the
+ * `sleepSync` in `file-lock.js` — the contract is identical; the
  * helper is duplicated here because rename-with-retry must not import the
  * larger file-lock module (cyclic-import risk: atomic-write imports
  * rename-with-retry, and file-lock imports atomic-write transitively
  * through the lock-event write path).
  *
+ * F-3a7c4d67 (sibling sweep): this file's own `ms <= 0` guard does NOT
+ * catch `ms = NaN` — every comparison with NaN is `false` in JS, so
+ * `NaN <= 0` is `false` and execution falls through to
+ * `Atomics.wait(view, 0, 0, NaN)`, independently confirmed (isolated
+ * one-liner, no repo writes) to hang the calling thread indefinitely, no
+ * bound, no error, no log line — the same defect class F-3a7c4d67 named in
+ * file-lock.js's sibling `sleepSync`, found here via that finding's own
+ * "sweep for every sibling" discipline, not named in the finding's own
+ * text. Reachable via `renameWithRetry(tmp, dest, { baseMs: NaN })` or
+ * `{ maxMs: NaN }` — `Math.min(NaN * 2**i, maxMs)` and
+ * `Math.min(baseMs * 2**i, NaN)` both evaluate to NaN, and the only current
+ * production caller (`atomic-write.js`) calls with zero options today, so
+ * this is latent-but-real against the function's own public option surface,
+ * not a live bug. Widened to the same `Number.isFinite` check
+ * `packages/ingest/lib/sleep-sync.js` already carries.
+ *
  * @param {number} ms
  */
 function sleepSync(ms) {
-  if (ms <= 0) return;
+  if (!Number.isFinite(ms) || ms <= 0) return;
   const sab = new SharedArrayBuffer(4);
   const view = new Int32Array(sab);
   Atomics.wait(view, 0, 0, ms);
 }
 
+/**
+ * Test-only: exercise the private `sleepSync` guard directly, without
+ * forcing a real EPERM/EBUSY filesystem race through `renameWithRetry`.
+ * Mirrors `file-lock.js`'s own `isLocked` test-only export precedent.
+ */
+export function __testSleepSync(ms) {
+  return sleepSync(ms);
+}
+
 export function renameWithRetry(tmp, dest, { retries = 10, baseMs = 15, maxMs = 200 } = {}) {
   for (let i = 0; i <= retries; i++) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/findings",
-  "version": "1.9.0",
+  "version": "1.10.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",
@@ -41,6 +41,7 @@
   "dependencies": {
     "@dogfood-lab/ingest": "^1.2.0",
     "@dogfood-lab/schemas": "^1.2.0",
+    "@dogfood-lab/verify": "^1.2.0",
     "js-yaml": "^4.1.0"
   },
   "engines": {

package/review/review-engine.js

@@ -21,11 +21,14 @@ import { atomicWriteFileSync } from '../lib/atomic-write.js';
  * contract: free-text prose and the four classification enums. Identity,
  * lineage, and evidence fields (finding_id, schema_version, source_record_ids,
  * evidence, status, …) are excluded — they are set by the pipeline, not edited
- * in place. The downstream write gate (dogfood-finding.schema.json's
- * additionalProperties:false + enum checks) is the enforcement boundary; this
- * list is what the CLI help renders so the documented set and the gate's
- * intent share one source. Editing an unlisted field is still refused post-hoc
- * by the schema gate — this constant narrows the help, not the enforcement.
+ * in place. This constant IS the enforcement boundary: performAction's edit
+ * loop refuses any `--set` field not listed here (fvr-002). The write-side
+ * schema gate (dogfood-finding.schema.json's additionalProperties:false + enum
+ * checks) is the SECOND line — it validates the VALUES of allowed fields — but
+ * it cannot be the identity gate, because a valid finding_id swapped for
+ * another valid finding_id is schema-valid yet breaks the id↔path invariant.
+ * The same list drives the CLI help so the documented set and the enforced set
+ * share one source.
  */
 export const EDITABLE_FIELDS = Object.freeze([
   'title',
@@ -111,6 +114,20 @@ export function performAction(rootDir, params) {
       if (field === '__proto__' || field === 'constructor' || field === 'prototype') {
         return { success: false, error: `Field "${field}" is not editable (reserved/unsafe key)` };
       }
+      // fvr-002 — allowlist enforcement, not just help text. `finding_id` (and
+      // every other identity/lineage/provenance field) is a VALID schema field,
+      // so mutating it to another well-formed value sails through the write-side
+      // schema gate while re-homing the finding's identity off its file path
+      // (findById matches the id INSIDE the file; the file still lands at the
+      // OLD path). The schema gate can only catch unknown/enum-invalid values,
+      // never a valid identity swapped for another valid one — so the allowlist
+      // is the enforcement boundary here, refusing anything `edit` is not for.
+      if (!EDITABLE_FIELDS.includes(field)) {
+        return {
+          success: false,
+          error: `Field "${field}" is not editable. Editable fields: ${EDITABLE_FIELDS.join(', ')}`
+        };
+      }
       const oldValue = finding[field];
       if (oldValue !== newValue) {
         fieldChanges[field] = { from: oldValue, to: newValue };

package/review/transitions.js

@@ -13,12 +13,121 @@
  *   any status -> candidate (except initial creation)
  */
 
-const TRANSITIONS = {
+/**
+ * F-271b4661 (wave 39, feature-pass integration finding) — cross-reference:
+ * this package's reopen/close guard vs. the swarm control-plane's C1/C2 verbs.
+ *
+ * docs/trajectory-and-closure.dispatch.md's Feature 2 (Closure Verbs) designs
+ * a FRESH guarded-reopen-with-mandatory-reason mechanism for the swarm's own
+ * per-run findings table: `swarm reopen` (C1) moves fixed|deferred|rejected
+ * -> recurring, requiring a non-empty reason AND evidence; `swarm close` (C2)
+ * closes a finding as fixed|rejected|deferred with a required `verified_how`.
+ * That is the SAME shape of guard this file already enforces, one package
+ * over, for a DIFFERENT 'finding':
+ *
+ *   - REQUIRES_CLOSED (below)     ~ C1's precondition that reopen is only
+ *     legal from a closed status (accepted/rejected here; fixed/deferred/
+ *     rejected on the control-plane side).
+ *   - REASON_REQUIRED (below)     ~ C2's mandatory `--reason` on `swarm
+ *     close`. NOT C1: `swarm close`'s closing dispositions are the local
+ *     analogue of this file's reject/invalidate/merge/supersede —
+ *     REASON_REQUIRED's actual members — but `swarm reopen` (C1) mandates
+ *     `--reason` AND `--evidence` while this file's own `reopen` action
+ *     carries NEITHER. That asymmetry is real, not a documentation gap; see
+ *     "NOT SHARED" below rather than assuming symmetry from this line alone.
+ *   - ACTION_TARGET_STATUS.reopen ~ C1's `recurring` target status — both
+ *     land a reopened item back in an amendable, non-terminal state
+ *     (`reviewed` here, `recurring` there), never in the original pre-review
+ *     state.
+ *   - lineage.superseded_by (dogfood-finding.schema.json) ~ T5's 'versions
+ *     supersede, nothing rewrites' — the same non-destructive-history
+ *     principle, expressed as a schema field here and as roadmap sequence
+ *     numbers + immutable finding_events rows on the control-plane side.
+ *
+ * SHARED DISCIPLINE (the same principle, independently earned in each place):
+ *   - a closed/terminal state is a PRECONDITION for reopening, never a target
+ *     (REQUIRES_CLOSED here; C1's own source-status check on the
+ *     control-plane side);
+ *   - history is additive — nothing here mutates a prior review-event-log
+ *     entry, nothing on the control-plane side edits a prior finding_events
+ *     row or a prior roadmap sequence; every reopen/close is itself a new,
+ *     evidence-bearing record layered on top of what came before.
+ *
+ * NOT SHARED, DISCLOSED (F-a50d8106 — wave-41 rider, canonicalized from the
+ * collect-swallowed local label B40-002 at the wave-43 merge; this cross-reference
+ * comment previously listed the next line as shared discipline, which
+ * overclaimed): the control-plane's C1 `swarm reopen` requires a non-empty
+ * `--reason` (and `--evidence`) as a hard CLI-layer precondition — cli.js's
+ * cmdReopen refuses before any DB write (packages/dogfood-swarm/cli.js).
+ * THIS file's own `reopen` action carries no such requirement:
+ * REASON_REQUIRED (above) is {reject, invalidate, merge, supersede} —
+ * 'reopen' is deliberately absent, so performAction (review-engine.js) and
+ * reviewArtifact (review-artifacts.js, which reuses the same REASON_REQUIRED
+ * set) both accept a reopen with no reason at all. review.test.js's own
+ * 'Review actions: reopen' suite is live evidence of the gap: its
+ * 'requires reason' case calls performAction with action:'reopen' and NO
+ * reason field, and asserts success — the test's name promised the opposite
+ * of what its body proves, which is exactly the kind of drift this note
+ * exists to stop happening again at the comment level. Silently-reopenable
+ * was never a deliberate design choice on this side, and this note does not
+ * argue it should stay that way — only that a cross-reference asserting
+ * false symmetry is worse than one naming the gap outright, per this repo's
+ * own honesty-is-a-feature ethos (swarms/CLAUDE.md). Adding 'reopen' to
+ * REASON_REQUIRED is a behavior change out of scope for a comment-only fix
+ * (F-271b4661's own precedent) and belongs to a follow-up finding.
+ *
+ * DELIBERATELY DISTINCT (do not converge these — they answer different
+ * questions for two different concepts that both happen to be named
+ * 'finding'):
+ *   - Granularity. This file's 'finding' is a distilled, reviewed,
+ *     cross-repo lesson (dogfood-finding.schema.json) — the synthesis
+ *     layer's output. The control-plane's 'finding' is a single dogfood-swarm
+ *     wave's raw defect row, scoped to one run. Merging the two vocabularies
+ *     would blur a reusable lesson with a per-run defect ticket.
+ *   - Status vocabulary. candidate/reviewed/accepted/rejected (TRANSITIONS,
+ *     below) vs. open/deferred/approved/fixed/rejected/recurring
+ *     (packages/dogfood-swarm/lib/finding-status.js). No 1:1 mapping is
+ *     attempted — reopen here targets 'reviewed' (an in-review state), C1
+ *     targets 'recurring' (an explicitly-reopened state distinct from a
+ *     fresh 'open' finding), because the two systems track different things
+ *     at different points in their lifecycle.
+ *   - Evidence shape. This file's REASON_REQUIRED actions attach a free-text
+ *     `decision_reason` (event-log.js) plus, for reject, a structured
+ *     `review.reject_reason` enum. C2 additionally requires `verified_how`
+ *     (independent|self_attested|operator_evidence) — a THIRD 'how do we
+ *     know' axis alongside this schema's own evidence[].evidence_kind (see
+ *     that property's own cross-reference note, F-936c83f4) and
+ *     packages/verify's --provenance=stub|github (see
+ *     validators/provenance.js's file header). Not the same question:
+ *     verified_how asks how a CLOSURE was verified; evidence_kind asks what
+ *     backs a distilled lesson; --provenance asks whether a submitted CI run
+ *     really happened.
+ *
+ * NO BEHAVIOR CHANGE. This is a comment-only fix (F-271b4661's recommendation
+ * option (a)) — it exists so a reader of either mechanism can find the other
+ * without re-deriving the comparison, and so the two vocabularies stay
+ * deliberately-distinct BY DECISION rather than accidentally-distinct because
+ * nobody had looked. C1/C2 are implemented in the swarm control plane
+ * (packages/dogfood-swarm — core/verbs domain, out of this package's scope);
+ * this file's own TRANSITIONS/REQUIRES_CLOSED/REASON_REQUIRED machinery is
+ * unchanged by this note.
+ */
+
+// F-937733ee: family sibling of F-2965699b/F-7ce07baa/verdict.js's
+// VERDICT_RANK. Object.create(null) removes the prototype chain, so
+// `TRANSITIONS['constructor']` is `undefined` rather than
+// `Object.prototype.constructor` (a truthy function) — the `if (!allowed)`
+// / `if (!TRANSITIONS[from])` unknown-status guards below fire correctly for
+// every Object.prototype key instead of going on to call `.has()` on a
+// built-in method and throwing a raw TypeError. `from` is currently always a
+// schema-enum-constrained finding status, so this is defense-in-depth for a
+// caller that skips that gate, not a live vector.
+const TRANSITIONS = Object.assign(Object.create(null), {
   candidate: new Set(['reviewed', 'accepted', 'rejected']),
   reviewed:  new Set(['accepted', 'rejected']),
   accepted:  new Set(['reviewed', 'rejected']),
   rejected:  new Set(['reviewed'])
-};
+});
 
 /**
  * Check if a status transition is lawful.

package/synthesis/apply-recommendation.js

@@ -95,8 +95,24 @@ export function applyRecommendation(rootDir, params) {
   // 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.
+  //
+  // F-853dbce9: the two-segment repo contract (F-54e5fde7 / V2-CROSS-BO-003)
+  // was NOT enforced here — the bare 2-way destructure silently DROPS every
+  // segment past the second, so `--policy group/subgroup/project` yielded
+  // pOrg='group', pRepo='subgroup' and resolved a DIFFERENT repo's policy
+  // file than the operator named, with no error on either the dry-run
+  // preview or the --write path. Matches persist.js:51's `segments.length
+  // !== 2` guard verbatim so the family reads identically.
   if (params.policyRepo) {
-    const [pOrg, pRepo] = String(params.policyRepo).split('/');
+    const segments = String(params.policyRepo).split('/');
+    if (segments.length !== 2) {
+      return structuredError(
+        'RECOMMENDATION_UNSAFE_POLICY',
+        `policy repo "${params.policyRepo}" is not a two-segment org/repo slug`,
+        'Nested GitLab subgroups are unsupported — pass --policy <org>/<repo>.'
+      );
+    }
+    const [pOrg, pRepo] = segments;
     if (!pOrg || !pRepo || isUnsafeSegment(pOrg) || isUnsafeSegment(pRepo)) {
       return structuredError(
         'RECOMMENDATION_UNSAFE_POLICY',
@@ -196,7 +212,18 @@ export function applyRecommendation(rootDir, params) {
   }
 
   // Apply the structured intent: add target to surfaces.<surface>.required_scenarios.
-  if (!policy.surfaces) policy.surfaces = {};
+  //
+  // F-5dfddcb5: policy.surfaces is a dynamic-key container (`[surface]`,
+  // below) built from a value this module does not itself constrain to a
+  // safe enum — Object.create(null) so a `surface` value of '__proto__'
+  // reassigns an own data property instead of the object's [[Prototype]].
+  // Mirrors the identical fix already shipped in this domain for the same
+  // assignment shape: packages/ingest/rebuild-indexes.js (F-89b7dcd5),
+  // packages/portfolio/lib/compute-trends.js (F-a853fcaa). Not reachable
+  // today — `surface` comes from `rec.applies_to.product_surfaces`, which is
+  // schema-enum-constrained — but this is the same defense-in-depth posture
+  // the sibling fixes already established for this pattern.
+  if (!policy.surfaces) policy.surfaces = Object.create(null);
   if (!policy.surfaces[surface]) policy.surfaces[surface] = {};
   if (!Array.isArray(policy.surfaces[surface].required_scenarios)) {
     policy.surfaces[surface].required_scenarios = [];
@@ -209,7 +236,28 @@ export function applyRecommendation(rootDir, params) {
   // 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 = {};
+  //
+  // F-5dfddcb5: Object.create(null), not {} — action.target is FREE TEXT
+  // (≤100 chars, no enum constraint, per this file's own header docstring)
+  // used as the dynamic key immediately below. On a plain {}, the bracket
+  // assignment `container['__proto__'] = provenance` does not create an own
+  // '__proto__' data property — it invokes Object.prototype's __proto__
+  // SETTER, which reassigns the CONTAINER's own [[Prototype]] to the
+  // provenance object. The write silently vanishes (Object.keys() stays [])
+  // and the container starts inheriting provenance's own properties instead
+  // — confirmed with a standalone probe matching this exact single-assignment
+  // shape. (This is scoped to the one container object, not a write onto the
+  // shared, global Object.prototype — that stronger form needs a read-then-
+  // write through an unguarded lookup, which is a different pattern.)
+  // Object.create(null) removes the [[Prototype]] chain entirely, so
+  // '__proto__' is just an ordinary key. NOT reachable from untrusted input
+  // today — the only current producer (recommendation-derivation.js's
+  // selectTemplate()) emits hardcoded literal targets — but a future
+  // template letting action.target reflect free-form scenario-id-shaped text
+  // must not silently reopen this class. Mirrors the identical fix already
+  // shipped for this pattern: packages/ingest/rebuild-indexes.js
+  // (F-89b7dcd5), packages/portfolio/lib/compute-trends.js (F-a853fcaa).
+  if (!policy.applied_recommendations) policy.applied_recommendations = Object.create(null);
   const provenance = {
     recommendation_id: id,
     action_type: action.type,
@@ -252,8 +300,23 @@ export function applyRecommendation(rootDir, params) {
   };
 }
 
-/** Resolve the on-disk path for a repo policy under rootDir. */
+/**
+ * Resolve the on-disk path for a repo policy under rootDir.
+ *
+ * F-853dbce9: fails closed on the same two-segment invariant the guard above
+ * enforces, rather than trusting every caller to have checked first —
+ * mirrors persist.js's computeRecordPath, which owns this same invariant at
+ * the write layer instead of trusting its own callers. Both of this
+ * function's current callers (the dry-run preview and the --write path) are
+ * already gated by the guard above, so this throw is defense-in-depth, not
+ * the primary enforcement point — but a future call site that skips the
+ * guard must fail loud here, not silently resolve a different repo's file.
+ */
 function policyPathFor(rootDir, orgRepo) {
-  const [org, repo] = orgRepo.split('/');
+  const segments = String(orgRepo).split('/');
+  if (segments.length !== 2 || !segments[0] || !segments[1]) {
+    throw new Error(`policy repo "${orgRepo}" is not a two-segment org/repo slug`);
+  }
+  const [org, repo] = segments;
   return resolve(rootDir, 'policies', 'repos', org, `${repo}.yaml`);
 }