@maintainabilityai/research-runner 0.1.1

package/dist/runner/nodes/clone-and-index.js

@@ -0,0 +1,158 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloneAndIndex = cloneAndIndex;
+/**
+ * clone_and_index — pure node (archaeology path).
+ *
+ * Shallow-clones the target repo into a temp directory, walks the file
+ * tree, and returns an inventory + the clone SHA. We skip non-source
+ * directories (.git, node_modules, dist, build, .next, target,
+ * __pycache__, venv) to keep the inventory honest.
+ *
+ * Phase 3a doesn't parse any code yet — that's analyze_architecture's
+ * job. This node is small + pure + fast so the orchestrator can decide
+ * whether to even bother analyzing (e.g. an empty repo or a docs-only
+ * mirror short-circuits to a node_error before we burn LLM tokens).
+ */
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const SKIP_DIRS = new Set([
+    '.git', 'node_modules', 'dist', 'build', '.next', 'target',
+    '__pycache__', '.venv', 'venv', '.pytest_cache', '.cache',
+    '.terraform', '.gradle', 'out', '.vs', '.idea',
+]);
+const KNOWN_MANIFESTS = new Set([
+    'package.json', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock',
+    'pyproject.toml', 'requirements.txt', 'setup.py', 'pipfile',
+    'cargo.toml', 'cargo.lock',
+    'go.mod', 'go.sum',
+    'pom.xml', 'build.gradle', 'build.gradle.kts',
+    'gemfile', 'gemfile.lock',
+    'composer.json', 'composer.lock',
+    'mix.exs',
+]);
+/** Max source files to enumerate by name (audit log payload control). */
+const MAX_SOURCE_FILES = 200;
+function cloneAndIndex(opts) {
+    if (!/^[\w.-]+\/[\w.-]+$/.test(opts.targetRepo)) {
+        throw new Error(`clone_and_index: invalid targetRepo "${opts.targetRepo}"; expected owner/repo`);
+    }
+    const parentDir = opts.parentDir ?? os.tmpdir();
+    fs.mkdirSync(parentDir, { recursive: true });
+    const cloneDir = fs.mkdtempSync(path.join(parentDir, 'archeologist-clone-'));
+    const originUrl = opts.originUrl ?? `https://github.com/${opts.targetRepo}.git`;
+    const cloneArgs = ['clone', '--depth', '1', '--single-branch', originUrl, cloneDir];
+    if (opts.ref) {
+        cloneArgs.splice(0, cloneArgs.length, 'clone', '--depth', '1', '--branch', opts.ref, originUrl, cloneDir);
+    }
+    const cloneResult = (0, node_child_process_1.spawnSync)('git', cloneArgs, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
+    if (cloneResult.status !== 0) {
+        fs.rmSync(cloneDir, { recursive: true, force: true });
+        throw new Error(`clone_and_index: git clone failed (status=${cloneResult.status}): ${(cloneResult.stderr || '').slice(0, 400)}`);
+    }
+    const shaResult = (0, node_child_process_1.spawnSync)('git', ['rev-parse', 'HEAD'], { cwd: cloneDir, stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' });
+    const cloneSha = (shaResult.stdout || '').trim();
+    if (!/^[0-9a-f]{7,40}$/.test(cloneSha)) {
+        fs.rmSync(cloneDir, { recursive: true, force: true });
+        throw new Error('clone_and_index: failed to resolve clone HEAD SHA after clone');
+    }
+    const inventory = walkInventory(cloneDir);
+    return { cloneDir, cloneSha, inventory };
+}
+/** Recursive walker that respects SKIP_DIRS and caps the enumerated sourceFiles list. */
+function walkInventory(rootDir) {
+    const inventory = {
+        totalFiles: 0,
+        totalBytes: 0,
+        byExtension: {},
+        rootManifests: [],
+        topLevelEntries: [],
+        sourceFiles: [],
+    };
+    // Top-level entries (preserve original case so it's obvious if "Api" vs "api")
+    const topLevel = fs.readdirSync(rootDir, { withFileTypes: true });
+    for (const ent of topLevel) {
+        if (SKIP_DIRS.has(ent.name.toLowerCase())) {
+            continue;
+        }
+        inventory.topLevelEntries.push(ent.name);
+        if (ent.isFile() && KNOWN_MANIFESTS.has(ent.name.toLowerCase())) {
+            inventory.rootManifests.push(ent.name);
+        }
+    }
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (SKIP_DIRS.has(ent.name.toLowerCase())) {
+                continue;
+            }
+            const full = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!ent.isFile()) {
+                continue;
+            }
+            let stat;
+            try {
+                stat = fs.statSync(full);
+            }
+            catch {
+                continue;
+            }
+            inventory.totalFiles += 1;
+            inventory.totalBytes += stat.size;
+            const ext = (path.extname(ent.name) || '<noext>').toLowerCase();
+            inventory.byExtension[ext] = (inventory.byExtension[ext] ?? 0) + 1;
+            if (inventory.sourceFiles.length < MAX_SOURCE_FILES) {
+                inventory.sourceFiles.push(path.relative(rootDir, full));
+            }
+        }
+    }
+    walk(rootDir);
+    // Sort byExtension descending by count for deterministic audit output
+    inventory.byExtension = Object.fromEntries(Object.entries(inventory.byExtension).sort((a, b) => b[1] - a[1]));
+    return inventory;
+}

package/dist/runner/nodes/dedupe-and-rank.d.ts

@@ -0,0 +1,27 @@
+/**
+ * dedupe_and_rank — pure node.
+ *
+ * Inputs: the flat list of ProviderResult from every search node
+ * (tavily, arxiv, uspto, hackernews — any combination).
+ *
+ * Behaviour:
+ *   1. Canonicalize URLs (lowercase host, strip default port, drop fragment,
+ *      drop trailing slash, drop common tracking query params).
+ *   2. Collapse duplicates by canonical URL — keep the highest-scoring
+ *      occurrence's title/excerpt, sum scores, multiply by a small recall
+ *      boost (1 + 0.15 × extra queries that surfaced the same source).
+ *   3. Sort desc by composite score, take top N (default 20).
+ *   4. Assign sequential S1, S2, … ids — the canonical citation tokens the
+ *      synthesis prompt references. Preserves provider, authors, and
+ *      publication date through to the published doc.
+ */
+import type { ProviderResult } from '../../search/provider-result';
+import type { RankedSource } from '../../schemas';
+export interface DedupeAndRankOpts {
+    /** Flat ProviderResult list across all providers. */
+    results: ProviderResult[];
+    topN?: number;
+    retrievedAt?: string;
+}
+export declare function canonicalizeUrl(rawUrl: string): string;
+export declare function dedupeAndRank(opts: DedupeAndRankOpts): RankedSource[];

package/dist/runner/nodes/dedupe-and-rank.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalizeUrl = canonicalizeUrl;
+exports.dedupeAndRank = dedupeAndRank;
+const TRACKING_PARAMS = new Set([
+    'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',
+    'gclid', 'fbclid', 'mc_cid', 'mc_eid', 'ref', 'ref_src', 'ref_url',
+]);
+function canonicalizeUrl(rawUrl) {
+    try {
+        const u = new URL(rawUrl.trim());
+        u.hostname = u.hostname.toLowerCase();
+        if ((u.protocol === 'http:' && u.port === '80') || (u.protocol === 'https:' && u.port === '443')) {
+            u.port = '';
+        }
+        for (const key of [...u.searchParams.keys()]) {
+            if (TRACKING_PARAMS.has(key.toLowerCase())) {
+                u.searchParams.delete(key);
+            }
+        }
+        u.hash = '';
+        let pathname = u.pathname.replace(/\/+$/, '');
+        if (pathname === '') {
+            pathname = '/';
+        }
+        u.pathname = pathname;
+        return u.toString();
+    }
+    catch {
+        return rawUrl.trim().toLowerCase();
+    }
+}
+function dedupeAndRank(opts) {
+    const topN = opts.topN ?? 20;
+    const retrievedAt = opts.retrievedAt ?? new Date().toISOString();
+    const bucket = new Map();
+    for (const r of opts.results) {
+        if (!r.url) {
+            continue;
+        }
+        const canonical = canonicalizeUrl(r.url);
+        const existing = bucket.get(canonical);
+        if (existing) {
+            existing.scoreSum += r.score;
+            existing.occurrences += 1;
+            existing.queries.add(r.fromQuery);
+            // Keep the highest-scoring occurrence's title/excerpt + first non-empty published/authors
+            if (r.score > existing.scoreSum / existing.occurrences) {
+                existing.title = r.title || existing.title;
+                if (r.content) {
+                    existing.excerpt = r.content.slice(0, 500);
+                }
+            }
+            if (!existing.publishedAt && r.publishedDate) {
+                existing.publishedAt = r.publishedDate;
+            }
+            if (!existing.authors && r.authors && r.authors.length > 0) {
+                existing.authors = r.authors;
+            }
+        }
+        else {
+            bucket.set(canonical, {
+                canonicalUrl: canonical,
+                provider: r.provider,
+                title: r.title || canonical,
+                excerpt: (r.content || '').slice(0, 500),
+                publishedAt: r.publishedDate,
+                authors: r.authors,
+                scoreSum: r.score,
+                occurrences: 1,
+                queries: new Set([r.fromQuery]),
+            });
+        }
+    }
+    const ranked = [...bucket.values()]
+        .map(a => {
+        const recall = 1 + 0.15 * (a.queries.size - 1);
+        const composite = Math.min(1, a.scoreSum * recall / Math.max(1, a.occurrences));
+        return { aggregated: a, composite };
+    })
+        .sort((a, b) => b.composite - a.composite)
+        .slice(0, topN);
+    return ranked.map((entry, i) => ({
+        id: `S${i + 1}`,
+        provider: entry.aggregated.provider,
+        title: entry.aggregated.title.slice(0, 300),
+        url: entry.aggregated.canonicalUrl,
+        retrieved_at: retrievedAt,
+        salience_score: roundTo(entry.composite, 4),
+        excerpt: entry.aggregated.excerpt.slice(0, 500),
+        ...(entry.aggregated.publishedAt ? { published_at: entry.aggregated.publishedAt } : {}),
+        ...(entry.aggregated.authors && entry.aggregated.authors.length > 0 ? { authors: entry.aggregated.authors } : {}),
+    }));
+}
+function roundTo(n, digits) {
+    const factor = 10 ** digits;
+    return Math.round(n * factor) / factor;
+}

package/dist/runner/nodes/deterministic-review.d.ts

@@ -0,0 +1,55 @@
+/**
+ * deterministic_architecture_review + deterministic_security_review
+ *
+ * Companion to the LLM expert reviewers — these are PURE (no LLM call) and
+ * grep-based. They produce the deterministic counter-signal verify_grounding
+ * needs to enforce the "both-must-pass" rule from the v0.6 spec:
+ *
+ *   - invalid_citations: PRD cites an ID that doesn't exist in the mesh
+ *                        (e.g. FR-02 traces to R5 but R5 was never declared;
+ *                         SR-01 cites THR-999 but mesh.bar.threats has none).
+ *   - coverage_discrepancies: the Coverage Analysis table claims YES/PARTIAL
+ *                             for a premise but no FR/SR actually cites it,
+ *                             or vice versa (says NO but body covers it).
+ *
+ * Severity: PASS if no invalid + no discrepancies. MINOR if only discrepancies.
+ * MAJOR if any invalid_citation. (Deterministic reviewers don't go to BLOCKING
+ * — that's an LLM-only judgment about substantive issues.)
+ */
+import type { MeshContext } from '../../schemas';
+import type { CoverageStatus, PrdCitationSignals } from './prd-validator';
+export type DeterministicExpertKind = 'architecture' | 'security';
+export type DeterministicSeverity = 'PASS' | 'MINOR' | 'MAJOR';
+export interface InvalidCitation {
+    /** Where the bad citation lives, e.g. "FR-02" or "SR-01" or "Coverage row R5". */
+    where: string;
+    cite: string;
+    reason: string;
+}
+export interface CoverageDiscrepancy {
+    premise: string;
+    claimed_status: CoverageStatus | 'MISSING_ROW';
+    observed: 'cited_by_body' | 'not_cited_by_body';
+    detail: string;
+}
+export interface DeterministicReview {
+    expert: DeterministicExpertKind;
+    iteration: number;
+    severity: DeterministicSeverity;
+    invalid_citations: InvalidCitation[];
+    coverage_discrepancies: CoverageDiscrepancy[];
+    /** Reviewer-specific stats — e.g. `{ calm_nodes_referenced: 3 }` for arch. */
+    stats: Record<string, number>;
+}
+export interface ArchitectureReviewOpts {
+    iteration: number;
+    signals: PrdCitationSignals;
+    meshContext: MeshContext;
+}
+export declare function deterministicArchitectureReview(opts: ArchitectureReviewOpts): DeterministicReview;
+export interface SecurityReviewOpts {
+    iteration: number;
+    signals: PrdCitationSignals;
+    meshContext: MeshContext;
+}
+export declare function deterministicSecurityReview(opts: SecurityReviewOpts): DeterministicReview;

package/dist/runner/nodes/deterministic-review.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deterministicArchitectureReview = deterministicArchitectureReview;
+exports.deterministicSecurityReview = deterministicSecurityReview;
+// OWASP Top 10 (2021) — what an A0X citation must match. v2026-04 catalog
+// stays at 2021 since the next revision is still draft as of this release;
+// when 2025 ships we add A11/etc. here.
+const OWASP_2021 = new Set(['A01', 'A02', 'A03', 'A04', 'A05', 'A06', 'A07', 'A08', 'A09', 'A10']);
+// NIST 800-53 control families — we don't validate the number, just the
+// family prefix. Catalog families per Rev 5.
+const NIST_FAMILIES = new Set([
+    'AC', 'AT', 'AU', 'CA', 'CM', 'CP', 'IA', 'IR', 'MA', 'MP',
+    'PE', 'PL', 'PM', 'PS', 'PT', 'RA', 'SA', 'SC', 'SI', 'SR', 'SU',
+]);
+function deterministicArchitectureReview(opts) {
+    const { iteration, signals } = opts;
+    const validPremises = new Set(signals.premise_ids);
+    const invalid = [];
+    // FR cites must reference declared premises (R[N] / E[N])
+    for (const fr of signals.fr_entries) {
+        for (const cite of fr.cited) {
+            if (!validPremises.has(cite)) {
+                invalid.push({
+                    where: fr.id,
+                    cite,
+                    reason: `Premise ${cite} not declared in Input Premises section`,
+                });
+            }
+        }
+    }
+    // Coverage discrepancies cross the table against actual FR citations
+    const discrepancies = computeCoverageDiscrepancies(signals, /*forSecurity*/ false);
+    // Stats: how many CALM nodes from the mesh are mentioned anywhere in the
+    // PRD body. We use the cached calm_node_ids set from MeshContext if present.
+    const calmIds = extractCalmNodeIds(opts.meshContext);
+    // Citation signals don't carry the raw body — we use the SR/FR cite arrays
+    // as a proxy: FRs with `CALM node:` hints would already have surfaced via
+    // generate-prd-manifest. Here we just count the in-scope CALM ids.
+    const stats = {
+        calm_nodes_in_scope: calmIds.size,
+        fr_count: signals.fr_entries.length,
+        sr_count: signals.sr_entries.length,
+    };
+    return {
+        expert: 'architecture',
+        iteration,
+        severity: severityFrom(invalid, discrepancies),
+        invalid_citations: invalid,
+        coverage_discrepancies: discrepancies,
+        stats,
+    };
+}
+function deterministicSecurityReview(opts) {
+    const { iteration, signals, meshContext } = opts;
+    const meshThreatIds = new Set();
+    const threats = meshContext.bar?.threats;
+    if (Array.isArray(threats)) {
+        for (const t of threats) {
+            if (t.id) {
+                meshThreatIds.add(t.id);
+            }
+        }
+    }
+    const invalid = [];
+    let threatCitations = 0;
+    let owaspCitations = 0;
+    let nistCitations = 0;
+    for (const sr of signals.sr_entries) {
+        for (const cite of sr.cited) {
+            if (cite.startsWith('THR-')) {
+                threatCitations += 1;
+                // Only validate when the mesh declares threats — if the BAR has
+                // no threats catalogue we can't say a THR-* cite is invalid.
+                if (meshThreatIds.size > 0 && !meshThreatIds.has(cite)) {
+                    invalid.push({
+                        where: sr.id,
+                        cite,
+                        reason: `Threat ${cite} not present in mesh.bar.threats`,
+                    });
+                }
+            }
+            else if (/^A\d{2}$/.test(cite)) {
+                owaspCitations += 1;
+                if (!OWASP_2021.has(cite)) {
+                    invalid.push({
+                        where: sr.id,
+                        cite,
+                        reason: `OWASP id ${cite} out of range (A01–A10 for 2021 catalog)`,
+                    });
+                }
+            }
+            else if (/^NIST-[A-Z]{2}-\d+$/.test(cite)) {
+                nistCitations += 1;
+                const family = cite.slice(5, 7);
+                if (!NIST_FAMILIES.has(family)) {
+                    invalid.push({
+                        where: sr.id,
+                        cite,
+                        reason: `NIST family ${family} not in 800-53 Rev 5 catalogue`,
+                    });
+                }
+            }
+        }
+    }
+    const discrepancies = computeCoverageDiscrepancies(signals, /*forSecurity*/ true);
+    const stats = {
+        sr_count: signals.sr_entries.length,
+        threat_citations: threatCitations,
+        owasp_citations: owaspCitations,
+        nist_citations: nistCitations,
+        threats_in_scope: meshThreatIds.size,
+    };
+    return {
+        expert: 'security',
+        iteration,
+        severity: severityFrom(invalid, discrepancies),
+        invalid_citations: invalid,
+        coverage_discrepancies: discrepancies,
+        stats,
+    };
+}
+// ============================================================================
+// Shared helpers
+// ============================================================================
+/**
+ * Compare the Coverage Analysis table against actual FR/SR citations.
+ *
+ * For each premise in the table:
+ *   - status YES/PARTIAL but no FR/SR cites it → 'cited_by_body=false' discrepancy
+ *   - status NO but at least one FR/SR cites it → 'cited_by_body=true' discrepancy
+ * For each premise NOT in the table but declared in Input Premises → MISSING_ROW
+ */
+function computeCoverageDiscrepancies(signals, _forSecurity) {
+    const out = [];
+    // Build the set of premises actually cited by any FR or SR.
+    const citedByBody = new Set();
+    for (const fr of signals.fr_entries) {
+        for (const c of fr.cited) {
+            citedByBody.add(c);
+        }
+    }
+    for (const sr of signals.sr_entries) {
+        for (const c of sr.cited) {
+            citedByBody.add(c);
+        }
+    }
+    const tablePremises = new Set(signals.coverage_rows.map(r => r.premise));
+    for (const row of signals.coverage_rows) {
+        const isCited = citedByBody.has(row.premise);
+        if ((row.status === 'YES' || row.status === 'PARTIAL') && !isCited) {
+            out.push({
+                premise: row.premise,
+                claimed_status: row.status,
+                observed: 'not_cited_by_body',
+                detail: `Coverage table claims ${row.status} but no FR/SR cites ${row.premise}`,
+            });
+        }
+        else if (row.status === 'NO' && isCited) {
+            out.push({
+                premise: row.premise,
+                claimed_status: row.status,
+                observed: 'cited_by_body',
+                detail: `Coverage table claims NO but body cites ${row.premise} in an FR/SR — table is stale`,
+            });
+        }
+    }
+    // Premises declared but missing from the table
+    for (const p of signals.premise_ids) {
+        if (!tablePremises.has(p)) {
+            out.push({
+                premise: p,
+                claimed_status: 'MISSING_ROW',
+                observed: citedByBody.has(p) ? 'cited_by_body' : 'not_cited_by_body',
+                detail: `Premise ${p} has no row in Coverage Analysis table`,
+            });
+        }
+    }
+    return out;
+}
+function severityFrom(invalid, discrepancies) {
+    if (invalid.length > 0) {
+        return 'MAJOR';
+    }
+    if (discrepancies.length > 0) {
+        return 'MINOR';
+    }
+    return 'PASS';
+}
+function extractCalmNodeIds(mesh) {
+    const out = new Set();
+    const calm = mesh.bar?.calm_model;
+    if (!calm || typeof calm !== 'object') {
+        return out;
+    }
+    const nodes = calm.nodes;
+    if (!Array.isArray(nodes)) {
+        return out;
+    }
+    for (const n of nodes) {
+        const id = n['unique-id'];
+        if (typeof id === 'string') {
+            out.add(id);
+        }
+    }
+    return out;
+}

package/dist/runner/nodes/expert-review.d.ts

@@ -0,0 +1,68 @@
+/**
+ * expert_review — shared LLM node for architecture_review + security_review.
+ *
+ * The two expert reviews differ only by:
+ *   - which `.caterpillar/prompts/prd/{architecture-review,security-review}.md`
+ *     pack they load
+ *   - which mesh context they receive (CALM nodes/ADRs for arch;
+ *     STRIDE/OWASP/NIST for sec)
+ *
+ * Both prompts contractually return a structured-text block:
+ *   SCORE: <float 0.00 - 1.00>
+ *   SEVERITY: <PASS | MINOR | MAJOR | BLOCKING>
+ *   COVERED: <comma-separated IDs>
+ *   MISSING: <comma-separated IDs>
+ *   CHANGES:
+ *   - <change 1>
+ *   - <change 2>
+ *
+ * We parse this with regex; the parser is lenient about whitespace + casing.
+ * Output flows directly into verify_grounding.
+ */
+import type { LlmProvider, MeshContext } from '../../schemas';
+import { type LoadedPrompt } from '../../mesh/prompt-loader';
+export type ExpertKind = 'architecture' | 'security';
+export type ReviewSeverity = 'PASS' | 'MINOR' | 'MAJOR' | 'BLOCKING';
+export interface ExpertReview {
+    expert: ExpertKind;
+    iteration: number;
+    score: number;
+    severity: ReviewSeverity;
+    /** Field names mirror GroundingBlock.iterations so verify_grounding can pass them through. */
+    covered_ids: string[];
+    missing_ids: string[];
+    changes: string[];
+}
+export interface ExpertReviewOpts {
+    meshDir: string;
+    expert: ExpertKind;
+    iteration: number;
+    prdBody: string;
+    meshContext: MeshContext;
+    /** Prior iteration's review (passed back to the LLM for delta-checking). */
+    priorReview?: ExpertReview;
+    provider: LlmProvider;
+    anthropicApiKey?: string;
+    githubToken?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface ExpertReviewResult {
+    review: ExpertReview;
+    prompt: LoadedPrompt;
+    llm: {
+        provider: LlmProvider;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+        attempts: number;
+    };
+}
+export declare function runExpertReview(opts: ExpertReviewOpts): Promise<ExpertReviewResult>;
+export declare function parseReviewResponse(raw: string, expert: ExpertKind, iteration: number): {
+    success: true;
+    data: ExpertReview;
+} | {
+    success: false;
+    error: string;
+};