@dogfood-lab/findings 1.3.2 → 1.5.0

package/synthesis/apply-recommendation.js

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

package/synthesis/dedupe-artifacts.js

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

package/synthesis/index.js

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

package/synthesis/pattern-derivation.js

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