@dogfood-lab/findings 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+<p align="center">
+  <a href="https://github.com/dogfood-lab/testing-os">
+    <img src="https://raw.githubusercontent.com/dogfood-lab/testing-os/main/assets/logo.png" alt="testing-os" width="280">
+  </a>
+</p>
+
+# @dogfood-lab/findings
+
+> Finding contract spine for testing-os. Validates, reads, lists, and queries evidence-bound findings — the fourth contract alongside record, scenario, and policy.
+
+Part of the [`testing-os`](https://github.com/dogfood-lab/testing-os) monorepo — the operating system for testing in the AI era.
+
+Findings are the evidence-bound observations produced by dogfood runs. Each finding is anchored to a specific source line, carries severity (`CRITICAL` / `HIGH` / `MEDIUM` / `LOW`) and status (`open` / `fixed` / `regressed` / etc.) fields, and feeds the four-stage intelligence pipeline: **derive → review → synthesize → advise**.
+
+## Install
+
+```bash
+npm install @dogfood-lab/findings
+```
+
+## CLI
+
+```bash
+npx @dogfood-lab/findings --help
+
+# Derive findings from records
+npx @dogfood-lab/findings derive --records-dir records/ --out findings/
+
+# Review pipeline (apply state transitions, build event log)
+npx @dogfood-lab/findings review --findings-dir findings/
+
+# Synthesize patterns + recommendations + doctrine
+npx @dogfood-lab/findings synthesize --findings-dir findings/
+
+# Query / advise downstream consumers
+npx @dogfood-lab/findings advise --topic <topic>
+```
+
+## Programmatic surface
+
+```js
+import { listFindings, readFinding } from '@dogfood-lab/findings/reader.js';
+import { validateFinding } from '@dogfood-lab/findings/validate.js';
+
+const findings = listFindings({ dir: './findings' });
+const first = readFinding(findings[0].path);
+
+const result = validateFinding(first);
+if (!result.ok) {
+  console.error(result.errors);
+}
+```
+
+## Pipeline stages
+
+| Stage | Module | Output |
+|---|---|---|
+| 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 |
+| Advise | `advise/advice-bundle.js`, `advise/query.js` | Advisory bundles for downstream consumers (e.g., `@dogfood-lab/dogfood-swarm`) |
+
+## Finding shape
+
+```yaml
+finding_id: F-XXXXXX-XXX
+severity: HIGH
+status: open
+title: <short imperative-mood phrase>
+evidence:
+  source_pin: { file: <path>, line: <n>, snippet: <verbatim> }
+  test_pin: { file: <path>, line: <n>, name: <test-name> }
+remediation:
+  approach: <strategy>
+  rationale: <why>
+```
+
+Full shape: `@dogfood-lab/schemas/json/dogfood-finding.schema.json`.
+
+## Atomic I/O (shared discipline)
+
+Internal helpers under `lib/`:
+
+- `atomic-write.js` — two-phase commit for finding-file writes (`writeFileSync` to shadow → `renameSync` to canonical)
+- `file-lock.js` — cross-process advisory lock via `linkSync` CAS, Windows-compatible
+- `rename-with-retry.js` — bounded retry on EPERM/EBUSY (Windows AV scanner handle-release window)
+
+These helpers are intentionally shared cross-package discipline. They're exported via the `./lib/*` subpath so `@dogfood-lab/dogfood-swarm` and `@dogfood-lab/ingest` can reuse the same atomic-write semantics. The CLAUDE.md in the repo root documents the cycle this creates and why it's accepted.
+
+## Docs
+
+📖 Full handbook: **<https://dogfood-lab.github.io/testing-os/handbook/>**
+
+## License
+
+MIT © 2026 mcp-tool-shop

package/advise/advice-bundle.js

@@ -0,0 +1,155 @@
+/**
+ * Advice bundle synthesis.
+ *
+ * Produces structured guidance bundles for future projects
+ * based on surface, execution mode, and archetype.
+ */
+
+import {
+  queryFindings,
+  queryPatterns,
+  queryRecommendations,
+  queryDoctrine,
+  queryFailureClasses
+} from './query.js';
+
+/**
+ * Generate an advice bundle for a given scope.
+ *
+ * @param {string} rootDir - dogfood-labs repo root
+ * @param {object} scope
+ * @param {string} [scope.surface] - product surface
+ * @param {string} [scope.executionMode] - bot/human/mixed
+ * @param {string} [scope.repo] - specific repo
+ * @param {string} [scope.journeyStage] - journey stage filter
+ * @param {string} [scope.issueKind] - issue kind filter
+ * @returns {object} Structured advice bundle
+ */
+export function generateAdviceBundle(rootDir, scope = {}) {
+  const recommendations = queryRecommendations(rootDir, scope);
+  const doctrine = queryDoctrine(rootDir, scope);
+  const patterns = queryPatterns(rootDir, scope);
+  const failureClasses = queryFailureClasses(rootDir, scope);
+  const findings = queryFindings(rootDir, { ...scope, limit: 8 });
+
+  // Categorize recommendations by kind
+  const starterChecks = recommendations.filter(r =>
+    r.recommendation_kind === 'starter_check' || r.recommendation_kind === 'starter_scenario'
+  );
+  const evidenceExpectations = recommendations.filter(r =>
+    r.recommendation_kind === 'evidence_expectation' || r.recommendation_kind === 'policy_seed'
+  );
+  const verificationRules = recommendations.filter(r =>
+    r.recommendation_kind === 'verification_rule' || r.recommendation_kind === 'review_prompt'
+  );
+
+  return {
+    query: {
+      product_surface: scope.surface || null,
+      execution_mode: scope.executionMode || null,
+      repo: scope.repo || null
+    },
+    advice: {
+      starter_checks: starterChecks.map(r => ({
+        id: r.recommendation_id,
+        title: r.title,
+        action: r.action,
+        confidence: r.confidence
+      })),
+      evidence_expectations: evidenceExpectations.map(r => ({
+        id: r.recommendation_id,
+        title: r.title,
+        action: r.action,
+        confidence: r.confidence
+      })),
+      verification_rules: verificationRules.map(r => ({
+        id: r.recommendation_id,
+        title: r.title,
+        action: r.action,
+        confidence: r.confidence
+      })),
+      likely_failure_classes: failureClasses,
+      relevant_doctrine: doctrine.map(d => ({
+        id: d.doctrine_id,
+        statement: d.statement,
+        strength: d.strength,
+        kind: d.doctrine_kind
+      }))
+    },
+    support: {
+      pattern_ids: patterns.map(p => p.pattern_id),
+      finding_ids: findings.map(f => f.finding_id),
+      pattern_count: patterns.length,
+      finding_count: findings.length,
+      recommendation_count: recommendations.length,
+      doctrine_count: doctrine.length
+    }
+  };
+}
+
+/**
+ * Generate a sync-friendly export of all accepted artifacts.
+ * For repo-knowledge consumption.
+ *
+ * @param {string} rootDir
+ * @returns {object} Export bundle with all accepted artifacts and lineage
+ */
+export function generateSyncExport(rootDir) {
+  const findings = queryFindings(rootDir, { limit: 500 });
+  const patterns = queryPatterns(rootDir, { limit: 100 });
+  const recommendations = queryRecommendations(rootDir, { limit: 100 });
+  const doctrine = queryDoctrine(rootDir, { limit: 100 });
+
+  return {
+    exported_at: new Date().toISOString(),
+    source: 'dogfood-labs',
+    counts: {
+      findings: findings.length,
+      patterns: patterns.length,
+      recommendations: recommendations.length,
+      doctrine: doctrine.length
+    },
+    findings: findings.map(f => ({
+      finding_id: f.finding_id,
+      title: f.title,
+      repo: f.repo,
+      product_surface: f.product_surface,
+      issue_kind: f.issue_kind,
+      root_cause_kind: f.root_cause_kind,
+      remediation_kind: f.remediation_kind,
+      transfer_scope: f.transfer_scope,
+      summary: f.summary,
+      doctrine_statement: f.doctrine_statement
+    })),
+    patterns: patterns.map(p => ({
+      pattern_id: p.pattern_id,
+      title: p.title,
+      pattern_kind: p.pattern_kind,
+      pattern_strength: p.pattern_strength,
+      transfer_scope: p.transfer_scope,
+      summary: p.summary,
+      source_finding_ids: p.source_finding_ids,
+      dimensions: p.dimensions,
+      support: p.support
+    })),
+    recommendations: recommendations.map(r => ({
+      recommendation_id: r.recommendation_id,
+      title: r.title,
+      recommendation_kind: r.recommendation_kind,
+      confidence: r.confidence,
+      applies_to: r.applies_to,
+      action: r.action,
+      based_on_pattern_ids: r.based_on_pattern_ids
+    })),
+    doctrine: doctrine.map(d => ({
+      doctrine_id: d.doctrine_id,
+      title: d.title,
+      doctrine_kind: d.doctrine_kind,
+      strength: d.strength,
+      statement: d.statement,
+      rationale: d.rationale,
+      transfer_scope: d.transfer_scope,
+      based_on_pattern_ids: d.based_on_pattern_ids
+    }))
+  };
+}

package/advise/index.js

@@ -0,0 +1,5 @@
+/**
+ * Advise layer exports.
+ */
+export { queryFindings, queryPatterns, queryRecommendations, queryDoctrine, queryFailureClasses } from './query.js';
+export { generateAdviceBundle, generateSyncExport } from './advice-bundle.js';

package/advise/query.js

@@ -0,0 +1,182 @@
+/**
+ * Query layer over accepted dogfood learning artifacts.
+ *
+ * Retrieves findings, patterns, recommendations, and doctrine
+ * filtered by surface, execution mode, journey stage, issue kind,
+ * and transfer scope. Respects ranking and caps.
+ */
+
+import { loadFindings } from '../reader.js';
+import { loadPatterns, loadRecommendations, loadDoctrines } from '../synthesis/write-artifacts.js';
+
+/**
+ * Query accepted findings by scope.
+ *
+ * @param {string} rootDir
+ * @param {object} scope
+ * @param {string} [scope.surface]
+ * @param {string} [scope.executionMode]
+ * @param {string} [scope.journeyStage]
+ * @param {string} [scope.issueKind]
+ * @param {string} [scope.repo]
+ * @param {number} [scope.limit=8]
+ * @returns {Array}
+ */
+export function queryFindings(rootDir, scope = {}) {
+  const all = loadFindings(rootDir);
+  const limit = scope.limit || 8;
+
+  const accepted = all.filter(f =>
+    f.valid &&
+    f.data?.status === 'accepted' &&
+    !f.data?.invalidation?.is_invalidated
+  );
+
+  let results = accepted.map(f => f.data);
+
+  if (scope.surface) results = results.filter(f => f.product_surface === scope.surface);
+  if (scope.executionMode) results = results.filter(f => f.execution_mode === scope.executionMode);
+  if (scope.journeyStage) results = results.filter(f => f.journey_stage === scope.journeyStage);
+  if (scope.issueKind) results = results.filter(f => f.issue_kind === scope.issueKind);
+  if (scope.repo) results = results.filter(f => f.repo === scope.repo);
+
+  // Rank: more specific transfer_scope first, then by surface match
+  results = rankByRelevance(results, scope);
+
+  return results.slice(0, limit);
+}
+
+/**
+ * Query accepted patterns by scope.
+ */
+export function queryPatterns(rootDir, scope = {}) {
+  const all = loadPatterns(rootDir);
+  const limit = scope.limit || 5;
+
+  let results = all.filter(p =>
+    p.status === 'accepted' &&
+    !(p.review?.last_action === 'invalidate')
+  );
+
+  if (scope.surface) {
+    results = results.filter(p =>
+      (p.dimensions?.product_surfaces || []).includes(scope.surface)
+    );
+  }
+  if (scope.issueKind) {
+    results = results.filter(p =>
+      (p.dimensions?.issue_kinds || []).includes(scope.issueKind)
+    );
+  }
+
+  // Rank: strong > emerging, more specific scope first
+  results.sort((a, b) => {
+    const strengthOrder = { portfolio_stable: 0, strong: 1, emerging: 2 };
+    const aStr = strengthOrder[a.pattern_strength] ?? 3;
+    const bStr = strengthOrder[b.pattern_strength] ?? 3;
+    if (aStr !== bStr) return aStr - bStr;
+    return scopeSpecificity(b.transfer_scope) - scopeSpecificity(a.transfer_scope);
+  });
+
+  return results.slice(0, limit);
+}
+
+/**
+ * Query accepted recommendations by scope.
+ */
+export function queryRecommendations(rootDir, scope = {}) {
+  const all = loadRecommendations(rootDir);
+  const limit = scope.limit || 5;
+
+  let results = all.filter(r => r.status === 'accepted');
+
+  if (scope.surface) {
+    results = results.filter(r =>
+      (r.applies_to?.product_surfaces || []).includes(scope.surface)
+    );
+  }
+  if (scope.executionMode) {
+    results = results.filter(r =>
+      !r.applies_to?.execution_modes?.length ||
+      r.applies_to.execution_modes.includes(scope.executionMode)
+    );
+  }
+
+  // Rank: strong confidence > emerging
+  results.sort((a, b) => {
+    const confOrder = { proven: 0, strong: 1, emerging: 2 };
+    return (confOrder[a.confidence] ?? 3) - (confOrder[b.confidence] ?? 3);
+  });
+
+  return results.slice(0, limit);
+}
+
+/**
+ * Query accepted doctrine by scope.
+ */
+export function queryDoctrine(rootDir, scope = {}) {
+  const all = loadDoctrines(rootDir);
+  const limit = scope.limit || 5;
+
+  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
+    );
+  }
+
+  results.sort((a, b) => {
+    const strOrder = { foundational: 0, proven: 1, emerging: 2 };
+    return (strOrder[a.strength] ?? 3) - (strOrder[b.strength] ?? 3);
+  });
+
+  return results.slice(0, limit);
+}
+
+/**
+ * Extract top failure classes from accepted findings for a scope.
+ */
+export function queryFailureClasses(rootDir, scope = {}) {
+  const findings = queryFindings(rootDir, { ...scope, limit: 50 });
+  const counts = new Map();
+
+  for (const f of findings) {
+    const key = f.issue_kind;
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+
+  return [...counts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 3)
+    .map(([issueKind, count]) => ({ issueKind, count }));
+}
+
+// ─── Ranking helpers ────────────────────────────────────────
+
+const SCOPE_ORDER = ['repo_local', 'surface_local', 'surface_archetype', 'execution_mode', 'org_wide'];
+
+function scopeSpecificity(scope) {
+  const idx = SCOPE_ORDER.indexOf(scope);
+  return idx >= 0 ? SCOPE_ORDER.length - idx : 0; // higher = more specific
+}
+
+function rankByRelevance(findings, scope) {
+  return findings.sort((a, b) => {
+    // Exact surface match first
+    const aSurface = scope.surface && a.product_surface === scope.surface ? 1 : 0;
+    const bSurface = scope.surface && b.product_surface === scope.surface ? 1 : 0;
+    if (aSurface !== bSurface) return bSurface - aSurface;
+
+    // More specific scope first
+    const aSpec = scopeSpecificity(a.transfer_scope);
+    const bSpec = scopeSpecificity(b.transfer_scope);
+    if (aSpec !== bSpec) return bSpec - aSpec;
+
+    return 0;
+  });
+}