@maintainabilityai/research-runner 0.1.1

package/dist/runner/nodes/synthesize-report.d.ts

@@ -0,0 +1,53 @@
+/**
+ * synthesize_report — LLM node.
+ *
+ * Second LLM hop in the archeologist research path. Loads
+ * `.caterpillar/prompts/research/synthesis.md`, fills it with the brief +
+ * mesh context + ranked sources + gap_analysis flag, calls Anthropic
+ * (sonnet by default — synthesis is more demanding than planning),
+ * runs the structural validator on the body, and either returns the
+ * validated body or retries once with feedback.
+ *
+ * Returns the synthesised body, the prompt-pack telemetry (path + sha256),
+ * LLM token/cost totals, and the citation_stats the audit log + Hatter's
+ * Tag both consume.
+ */
+import type { ArchaeologyGap, LlmProvider, MeshContext, ObservedArchitecture, RankedSource, ResearchBrief, ResearchPath } from '../../schemas';
+import { type LoadedPrompt } from '../../mesh/prompt-loader';
+import { type CitationStats, type ValidationReport } from './synthesis-validator';
+export interface SynthesizeReportOpts {
+    meshDir: string;
+    brief: ResearchBrief;
+    meshContext: MeshContext;
+    rankedSources: RankedSource[];
+    /** Provider routing — comes from brief.llm_provider unless overridden. */
+    provider?: LlmProvider;
+    /** Required when provider === 'anthropic'. */
+    anthropicApiKey?: string;
+    /** Required when provider === 'github-models'. */
+    githubToken?: string;
+    /** Flipped true by the orchestrator after gap-analysis fires. */
+    gapAnalysisRan?: boolean;
+    /** Defaults to brief.path. Overrideable for tests. */
+    path?: ResearchPath;
+    /** Archaeology-path only: observed architecture extracted from the target repo. */
+    observedArchitecture?: ObservedArchitecture;
+    /** Archaeology-path only: gaps identified by identify_gaps. */
+    archaeologyGaps?: ArchaeologyGap[];
+    fetchImpl?: typeof fetch;
+}
+export interface SynthesizeReportResult {
+    body_md: string;
+    prompt: LoadedPrompt;
+    validation: ValidationReport;
+    citation_stats: CitationStats;
+    llm: {
+        provider: LlmProvider;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+        attempts: number;
+    };
+}
+export declare function synthesizeReport(opts: SynthesizeReportOpts): Promise<SynthesizeReportResult>;

package/dist/runner/nodes/synthesize-report.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.synthesizeReport = synthesizeReport;
+const llm_router_1 = require("../../llm/llm-router");
+const prompt_loader_1 = require("../../mesh/prompt-loader");
+const synthesis_validator_1 = require("./synthesis-validator");
+const synthesis_archaeology_validator_1 = require("./synthesis-archaeology-validator");
+const MAX_TOKENS = 8000;
+async function synthesizeReport(opts) {
+    const provider = opts.provider ?? opts.brief.llm_provider;
+    const path = opts.path ?? opts.brief.path;
+    // Two different prompt packs + validators per path. Same LLM router, same
+    // retry-with-feedback loop — only the pack name + the validator differ.
+    const packId = path === 'archaeology' ? 'research/synthesis-archaeology' : 'research/synthesis';
+    const validate = path === 'archaeology' ? synthesis_archaeology_validator_1.validateArchaeologySynthesis : synthesis_validator_1.validateSynthesis;
+    const promptContext = path === 'archaeology'
+        ? buildArchaeologyPromptContext(opts.brief, opts.meshContext, opts.rankedSources, opts.observedArchitecture, opts.archaeologyGaps ?? [])
+        : buildPromptContext(opts.brief, opts.meshContext, opts.rankedSources, opts.gapAnalysisRan ?? false);
+    const prompt = (0, prompt_loader_1.loadPrompt)({
+        meshDir: opts.meshDir,
+        packId,
+        context: promptContext,
+    });
+    const system = path === 'archaeology'
+        ? 'You write structured markdown architecture-archaeology reports with strict section discipline. Every gap (G[N]) carries a severity. Every Recommendation traces to a G[N] and cites at least one grounding token (S[N] or OA[…]). The 9 H2 sections appear in the exact order requested. No prose before the first `##` heading.'
+        : 'You write structured markdown documents with strict section + citation discipline. Every claim has an S[N] citation; every C[N] cites ≥2 sources; every Recommendation traces to a C[N]. Headings appear in the exact order requested. No prose before the first `##` heading.';
+    let lastReport = null;
+    let totalInput = 0;
+    let totalOutput = 0;
+    let totalCost = 0;
+    let lastModel = '';
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        const userPrompt = attempt === 1
+            ? prompt.filled
+            : `${prompt.filled}\n\n---\n\nYour previous response failed structural validation:\n${lastReport.errors.map(e => `- ${e}`).join('\n')}\n\nRewrite the document and fix EVERY error above. The 10 H2 sections must appear in the exact order specified; every C[N] must cite ≥2 S[N] (or ≥1 if confidence is LOW); every Recommendation must reference at least one C[N].`;
+        const result = await (0, llm_router_1.callLlm)({
+            provider,
+            tier: 'synth',
+            anthropicApiKey: opts.anthropicApiKey,
+            githubToken: opts.githubToken,
+            system,
+            prompt: userPrompt,
+            maxTokens: MAX_TOKENS,
+            fetchImpl: opts.fetchImpl,
+        });
+        totalInput += result.inputTokens;
+        totalOutput += result.outputTokens;
+        totalCost += result.costUsd;
+        lastModel = result.model;
+        const body = stripFences(result.text);
+        const report = validate(body);
+        if (report.valid) {
+            return {
+                body_md: body,
+                prompt,
+                validation: report,
+                citation_stats: report.citation_stats,
+                llm: { provider, model: lastModel, inputTokens: totalInput, outputTokens: totalOutput, costUsd: totalCost, attempts: attempt },
+            };
+        }
+        lastReport = report;
+    }
+    throw new Error(`synthesize_report: structural validation failed after 2 attempts. Last errors: ${lastReport.errors.join('; ')}`);
+}
+/** If the model wraps the doc in ```markdown … ``` fences, unwrap. Otherwise pass through. */
+function stripFences(raw) {
+    const trimmed = raw.trim();
+    const fenceMatch = trimmed.match(/^```(?:markdown|md)?\s*([\s\S]*?)```\s*$/);
+    return fenceMatch ? fenceMatch[1].trim() : trimmed;
+}
+/** Build the dotted-key context the synthesis prompt asks for. */
+function buildPromptContext(brief, mesh, rankedSources, gapAnalysisRan) {
+    return {
+        brief: {
+            topic: brief.topic,
+            scope_level: brief.scope.level,
+        },
+        mesh: {
+            context_summary: summarizeMeshContext(mesh),
+        },
+        ranked_sources: rankedSources.length === 0
+            ? '(no sources retrieved)'
+            : rankedSources.map(formatRankedSource).join('\n\n'),
+        gap_analysis_ran: gapAnalysisRan,
+    };
+}
+function summarizeMeshContext(mesh) {
+    const parts = [];
+    parts.push(`Portfolio: ${mesh.portfolio.name}`);
+    if (mesh.portfolio.related_research_summaries.length > 0) {
+        parts.push(`Portfolio research (${mesh.portfolio.related_research_summaries.length}): ${mesh.portfolio.related_research_summaries.map(r => r.topic).slice(0, 5).join('; ')}`);
+    }
+    if (mesh.platform) {
+        parts.push(`Platform: ${mesh.platform.platform_id} (${mesh.platform.sibling_bars.length} sibling BAR${mesh.platform.sibling_bars.length === 1 ? '' : 's'})`);
+    }
+    if (mesh.bar) {
+        parts.push(`BAR: ${mesh.bar.name} (${mesh.bar.bar_id}); tier=${mesh.bar.tier}; ADRs=${mesh.bar.adrs.length}; prior research=${mesh.bar.related_research.length}; prior PRDs=${mesh.bar.related_prds.length}; mesh gaps: ${mesh.bar.mesh_gaps.join(', ') || 'none'}`);
+        if (Array.isArray(mesh.bar.threats)) {
+            const ts = mesh.bar.threats;
+            parts.push(`STRIDE threats (${ts.length}): ${ts.map(t => `${t.id}/${t.category}`).slice(0, 6).join('; ')}`);
+        }
+    }
+    return parts.join('\n');
+}
+function formatRankedSource(s) {
+    const lines = [
+        `- **${s.id}** "${s.title}" (${s.provider}, salience ${s.salience_score})`,
+        `  URL: ${s.url}`,
+        `  Retrieved: ${s.retrieved_at}`,
+    ];
+    if (s.published_at) {
+        lines.push(`  Published: ${s.published_at}`);
+    }
+    if (s.excerpt) {
+        lines.push(`  Excerpt: ${s.excerpt.slice(0, 280)}${s.excerpt.length > 280 ? '…' : ''}`);
+    }
+    return lines.join('\n');
+}
+/** Build the dotted-key context the archaeology synthesis prompt asks for. */
+function buildArchaeologyPromptContext(brief, mesh, rankedSources, observed, gaps) {
+    return {
+        target_repo: brief.target_repo ?? '(unknown target)',
+        observed_architecture: observed
+            ? formatObservedArchitecture(observed)
+            : '(analyzer did not run)',
+        mesh: {
+            bar: {
+                calm_summary: mesh.bar?.calm_model ? summarizeCalmModelArchaeology(mesh.bar.calm_model) : '(no CALM model loaded)',
+                threats_summary: mesh.bar?.threats ? summarizeThreatsArchaeology(mesh.bar.threats) : '(no threat model on file)',
+            },
+        },
+        gap_signals: gaps.length === 0 ? '(no structural gaps detected)' : gaps.map(g => `- **${g.id}** [${g.severity}] ${g.kind}: ${g.summary}`).join('\n'),
+        ranked_sources: rankedSources.length === 0
+            ? '(no web sources retrieved)'
+            : rankedSources.map(formatRankedSource).join('\n\n'),
+    };
+}
+function formatObservedArchitecture(o) {
+    const lines = [];
+    lines.push(`Repo: ${o.profile.slug} @ ${o.profile.cloneSha.slice(0, 12)}`);
+    lines.push(`Languages: ${o.profile.languages.join(', ') || '(none detected)'}`);
+    lines.push(`Frameworks: ${o.profile.frameworks.join(', ') || '(none detected)'}`);
+    lines.push(`Manifests: ${o.profile.manifests.join(', ') || '(none)'}`);
+    lines.push(`Files: ${o.profile.totalFiles} totalling ${o.profile.totalBytes} bytes`);
+    lines.push('');
+    lines.push('Modules (top 12 by file count):');
+    for (const m of o.modules.slice(0, 12)) {
+        lines.push(`  - OA[${m.name}] layer=${m.layer} files=${m.fileCount} endpoints=${m.endpointCount}`);
+    }
+    if (o.endpoints.length > 0) {
+        lines.push('');
+        lines.push('Endpoints (sample):');
+        for (const e of o.endpoints.slice(0, 15)) {
+            lines.push(`  - ${e.method} ${e.path} (${e.framework}) — ${e.file}`);
+        }
+    }
+    if (o.dependencies.length > 0) {
+        lines.push('');
+        lines.push(`Direct dependencies (${o.dependencies.length}): ${o.dependencies.slice(0, 25).join(', ')}${o.dependencies.length > 25 ? ', …' : ''}`);
+    }
+    return lines.join('\n');
+}
+function summarizeCalmModelArchaeology(calm) {
+    if (!calm || typeof calm !== 'object') {
+        return '(no CALM model loaded)';
+    }
+    const obj = calm;
+    const nodes = Array.isArray(obj.nodes) ? obj.nodes : [];
+    const relationships = Array.isArray(obj.relationships) ? obj.relationships : [];
+    const lines = [];
+    lines.push(`${nodes.length} node(s), ${relationships.length} relationship(s)`);
+    for (const n of nodes.slice(0, 10)) {
+        const o = n;
+        lines.push(`  - ${o['unique-id'] ?? o.name ?? 'unknown'} (${o['node-type'] ?? 'unknown'})`);
+    }
+    return lines.join('\n');
+}
+function summarizeThreatsArchaeology(threats) {
+    if (!Array.isArray(threats) || threats.length === 0) {
+        return '(no threats)';
+    }
+    const byCategory = {};
+    for (const t of threats) {
+        const cat = t.category || 'unknown';
+        byCategory[cat] = (byCategory[cat] || 0) + 1;
+    }
+    return Object.entries(byCategory).map(([c, n]) => `${c} × ${n}`).join(', ');
+}

package/dist/runner/nodes/tavily-search.d.ts

@@ -0,0 +1,21 @@
+import type { ProviderResult } from '../../search/provider-result';
+export interface TavilySearchNodeOpts {
+    apiKey: string;
+    queries: string[];
+    maxResultsPerQuery?: number;
+    searchDepth?: 'basic' | 'advanced';
+    fetchImpl?: typeof fetch;
+}
+export interface QueryEnvelope {
+    query: string;
+    httpStatus: number;
+    responseBytes: number;
+    resultCount: number;
+    /** Populated when this query failed. */
+    error?: string;
+}
+export interface TavilySearchNodeResult {
+    envelopes: QueryEnvelope[];
+    results: ProviderResult[];
+}
+export declare function runTavilySearch(opts: TavilySearchNodeOpts): Promise<TavilySearchNodeResult>;

package/dist/runner/nodes/tavily-search.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTavilySearch = runTavilySearch;
+/**
+ * tavily_search — pure_api node.
+ *
+ * Runs every web query from the QueryPlan against Tavily in parallel.
+ * Per-query failures are isolated (one query failing doesn't kill the run);
+ * the orchestrator records per-query telemetry for the audit log.
+ *
+ * Emits ProviderResult[] tagged with provider='tavily' for the shared
+ * dedupe-and-rank step that handles results from every provider.
+ */
+const tavily_client_1 = require("../../search/tavily-client");
+async function runTavilySearch(opts) {
+    if (!opts.apiKey) {
+        throw new Error('TAVILY_API_KEY missing — set the env var or pass apiKey directly');
+    }
+    const settled = await Promise.allSettled(opts.queries.map(query => (0, tavily_client_1.tavilySearch)({
+        apiKey: opts.apiKey,
+        query,
+        maxResults: opts.maxResultsPerQuery ?? 5,
+        searchDepth: opts.searchDepth ?? 'basic',
+        fetchImpl: opts.fetchImpl,
+    })));
+    const envelopes = [];
+    const results = [];
+    for (let i = 0; i < opts.queries.length; i++) {
+        const query = opts.queries[i];
+        const outcome = settled[i];
+        if (outcome.status === 'fulfilled') {
+            const ok = outcome.value;
+            envelopes.push({
+                query,
+                httpStatus: ok.httpStatus,
+                responseBytes: ok.responseBytes,
+                resultCount: ok.results.length,
+            });
+            for (const r of ok.results) {
+                results.push({
+                    provider: 'tavily',
+                    fromQuery: query,
+                    title: r.title,
+                    url: r.url,
+                    content: r.content,
+                    score: r.score,
+                    publishedDate: r.publishedDate,
+                });
+            }
+        }
+        else {
+            const err = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+            envelopes.push({ query, httpStatus: 0, responseBytes: 0, resultCount: 0, error: err });
+        }
+    }
+    return { envelopes, results };
+}

package/dist/runner/nodes/uspto-search.d.ts

@@ -0,0 +1,13 @@
+import type { ProviderResult } from '../../search/provider-result';
+import type { QueryEnvelope } from './tavily-search';
+export interface UsptoSearchNodeOpts {
+    apiKey: string;
+    queries: string[];
+    maxResultsPerQuery?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface UsptoSearchNodeResult {
+    envelopes: QueryEnvelope[];
+    results: ProviderResult[];
+}
+export declare function runUsptoSearch(opts: UsptoSearchNodeOpts): Promise<UsptoSearchNodeResult>;

package/dist/runner/nodes/uspto-search.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runUsptoSearch = runUsptoSearch;
+/**
+ * uspto_search — pure_api node.
+ *
+ * Runs each patent query against USPTO's Open Data Portal
+ * (api.uspto.gov). Requires USPTO_API_KEY.
+ *
+ * Salience score derived from result position (descending; first hit
+ * gets 0.85, decays by 0.1 per position, floor at 0.4) since the ODP
+ * endpoint doesn't return its own relevance score.
+ *
+ * When no apiKey is supplied, this node throws — the orchestrator catches
+ * and converts to a node_error envelope so the run continues without
+ * patent coverage rather than failing entirely.
+ */
+const uspto_client_1 = require("../../search/uspto-client");
+async function runUsptoSearch(opts) {
+    if (!opts.apiKey) {
+        throw new Error('USPTO_API_KEY missing — request a key at https://data.uspto.gov/apis/getting-started');
+    }
+    const settled = await Promise.allSettled(opts.queries.map(query => (0, uspto_client_1.usptoSearch)({
+        apiKey: opts.apiKey,
+        query,
+        maxResults: opts.maxResultsPerQuery ?? 5,
+        fetchImpl: opts.fetchImpl,
+    })));
+    const envelopes = [];
+    const results = [];
+    for (let i = 0; i < opts.queries.length; i++) {
+        const query = opts.queries[i];
+        const outcome = settled[i];
+        if (outcome.status === 'fulfilled') {
+            const ok = outcome.value;
+            envelopes.push({
+                query,
+                httpStatus: ok.httpStatus,
+                responseBytes: ok.responseBytes,
+                resultCount: ok.results.length,
+            });
+            for (let j = 0; j < ok.results.length; j++) {
+                const r = ok.results[j];
+                results.push({
+                    provider: 'uspto',
+                    fromQuery: query,
+                    title: r.title,
+                    url: r.url,
+                    content: r.abstract.slice(0, 500),
+                    score: Math.max(0.4, 0.85 - j * 0.1),
+                    publishedDate: r.grantedAt || undefined,
+                    authors: r.inventors,
+                });
+            }
+        }
+        else {
+            const err = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+            envelopes.push({ query, httpStatus: 0, responseBytes: 0, resultCount: 0, error: err });
+        }
+    }
+    return { envelopes, results };
+}

package/dist/runner/nodes/verify-grounding.d.ts

@@ -0,0 +1,54 @@
+/**
+ * verify_grounding — pure node, v0.6.
+ *
+ * Combines FOUR signals to decide PASS / ITERATE / EXHAUSTED:
+ *   (1) deterministic_architecture_review — citation-grep against premises
+ *   (2) deterministic_security_review     — citation-grep against threats + OWASP + NIST
+ *   (3) architect_expert_review (LLM)     — SCORE/SEVERITY/COVERED/MISSING/CHANGES
+ *   (4) security_expert_review (LLM)      — same shape
+ *
+ * Plus the deterministic citation-coverage stats derived from PrdCitationSignals
+ * (threats covered, CALM nodes referenced, self-reported NOs).
+ *
+ * Verdict rules (v0.6 "both-must-pass" semantics):
+ *   - If EITHER deterministic reviewer is MAJOR (invalid citations exist),
+ *     ITERATE — no amount of LLM rubber-stamping can excuse a wrong cite.
+ *   - If the |arch_score − sec_score| disagreement is ≥ 0.2, ITERATE — the
+ *     experts disagree strongly, treat as "needs another pass".
+ *   - In strict mode, any BLOCKING LLM severity also forces ITERATE.
+ *   - Otherwise: PASS iff composite ≥ threshold.
+ *   - On the final allowed iteration, ITERATE becomes EXHAUSTED.
+ */
+import type { GroundingBlock, GroundingMode, MeshContext } from '../../schemas';
+import type { DeterministicReview } from './deterministic-review';
+import type { ExpertReview } from './expert-review';
+import type { PrdCitationSignals } from './prd-validator';
+export interface VerifyGroundingOpts {
+    iteration: number;
+    threshold: number;
+    mode: GroundingMode;
+    signals: PrdCitationSignals;
+    /** LLM reviewers — high-judgment scoring. */
+    architecture: ExpertReview;
+    security: ExpertReview;
+    /** Deterministic reviewers — citation grep. */
+    det_architecture: DeterministicReview;
+    det_security: DeterministicReview;
+    meshContext: MeshContext;
+    /** History of LLM reviews across prior iterations — for the GroundingBlock progression. */
+    history: ExpertReview[];
+}
+export type GroundingVerdict = 'PASS' | 'ITERATE' | 'EXHAUSTED';
+export interface VerifyGroundingResult {
+    verdict: GroundingVerdict;
+    grounding: GroundingBlock;
+    reason: string;
+    /** Per-iteration signals — what iteration_summary audit events record. */
+    signals_snapshot: {
+        composite_score: number;
+        disagreement_delta: number;
+    };
+}
+/** Disagreement threshold from the v0.6 spec — re-iterate when experts disagree this much. */
+export declare const DISAGREEMENT_DELTA_THRESHOLD = 0.2;
+export declare function verifyGrounding(opts: VerifyGroundingOpts): VerifyGroundingResult;

package/dist/runner/nodes/verify-grounding.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISAGREEMENT_DELTA_THRESHOLD = void 0;
+exports.verifyGrounding = verifyGrounding;
+/** Disagreement threshold from the v0.6 spec — re-iterate when experts disagree this much. */
+exports.DISAGREEMENT_DELTA_THRESHOLD = 0.2;
+function verifyGrounding(opts) {
+    const citation = computeCitationCoverage(opts.signals, opts.meshContext);
+    const compositeScore = combineScore(opts.architecture.score, opts.security.score, citation);
+    const disagreement = Math.abs(opts.architecture.score - opts.security.score);
+    const iterations = [
+        ...opts.history,
+        opts.architecture,
+        opts.security,
+    ];
+    const baseGrounding = {
+        final_iteration: opts.iteration,
+        iterations,
+        citation_coverage: citation,
+        final_score: round4(compositeScore),
+        passed: false, // overwritten below per verdict
+    };
+    // Rule 1: invalid citations from EITHER deterministic reviewer → ITERATE.
+    const detArchMajor = opts.det_architecture.severity === 'MAJOR';
+    const detSecMajor = opts.det_security.severity === 'MAJOR';
+    if (detArchMajor || detSecMajor) {
+        return {
+            verdict: 'ITERATE',
+            grounding: baseGrounding,
+            reason: `Deterministic reviewer flagged invalid citations (det_arch=${opts.det_architecture.severity}/${opts.det_architecture.invalid_citations.length}, det_sec=${opts.det_security.severity}/${opts.det_security.invalid_citations.length}) — the PRD references IDs that don't exist in the mesh. Composite=${round4(compositeScore)} ignored until cites are fixed.`,
+            signals_snapshot: { composite_score: round4(compositeScore), disagreement_delta: round4(disagreement) },
+        };
+    }
+    // Rule 2: BLOCKING LLM severity in strict mode → ITERATE.
+    const hasBlocking = opts.architecture.severity === 'BLOCKING' || opts.security.severity === 'BLOCKING';
+    if (opts.mode === 'strict' && hasBlocking) {
+        return {
+            verdict: 'ITERATE',
+            grounding: baseGrounding,
+            reason: `BLOCKING review in strict mode (arch=${opts.architecture.severity}, sec=${opts.security.severity}) — re-iterate even though composite=${round4(compositeScore)} would otherwise pass.`,
+            signals_snapshot: { composite_score: round4(compositeScore), disagreement_delta: round4(disagreement) },
+        };
+    }
+    // Rule 3: expert disagreement ≥ DISAGREEMENT_DELTA_THRESHOLD → ITERATE.
+    if (disagreement >= exports.DISAGREEMENT_DELTA_THRESHOLD) {
+        return {
+            verdict: 'ITERATE',
+            grounding: baseGrounding,
+            reason: `Expert disagreement ${round4(disagreement)} ≥ ${exports.DISAGREEMENT_DELTA_THRESHOLD} (arch=${opts.architecture.score}, sec=${opts.security.score}) — re-iterate so the experts can converge.`,
+            signals_snapshot: { composite_score: round4(compositeScore), disagreement_delta: round4(disagreement) },
+        };
+    }
+    // Rule 4: composite ≥ threshold → PASS.
+    if (compositeScore >= opts.threshold) {
+        return {
+            verdict: 'PASS',
+            grounding: { ...baseGrounding, passed: true },
+            reason: `composite=${round4(compositeScore)} ≥ threshold=${opts.threshold}; arch=${opts.architecture.score}/${opts.architecture.severity}; sec=${opts.security.score}/${opts.security.severity}; det_arch=${opts.det_architecture.severity}; det_sec=${opts.det_security.severity}; disagreement=${round4(disagreement)}.`,
+            signals_snapshot: { composite_score: round4(compositeScore), disagreement_delta: round4(disagreement) },
+        };
+    }
+    return {
+        verdict: 'ITERATE',
+        grounding: baseGrounding,
+        reason: `composite=${round4(compositeScore)} < threshold=${opts.threshold} (arch=${opts.architecture.score} × sec=${opts.security.score}; under-cited FR=${citation.calm_nodes_in_scope - citation.calm_nodes_cited_by_fr}, under-cited threats=${citation.threats_in_scope - citation.threats_covered_by_sr}, self-reported NO=${citation.self_reported_no_count}).`,
+        signals_snapshot: { composite_score: round4(compositeScore), disagreement_delta: round4(disagreement) },
+    };
+}
+// ============================================================================
+// Citation coverage (deterministic — unchanged from earlier phase)
+// ============================================================================
+function computeCitationCoverage(signals, mesh) {
+    const strideIdsInScope = new Set();
+    if (Array.isArray(mesh.bar?.threats)) {
+        for (const t of mesh.bar.threats) {
+            if (t.id) {
+                strideIdsInScope.add(t.id);
+            }
+        }
+    }
+    const threatsCitedBySr = new Set();
+    for (const sr of signals.sr_entries) {
+        for (const cite of sr.cited) {
+            if (cite.startsWith('THR-')) {
+                threatsCitedBySr.add(cite);
+            }
+        }
+    }
+    const calmNodesInScope = new Set();
+    const calm = mesh.bar?.calm_model;
+    if (calm && typeof calm === 'object') {
+        const nodes = calm.nodes;
+        if (Array.isArray(nodes)) {
+            for (const n of nodes) {
+                const id = n['unique-id'];
+                if (typeof id === 'string') {
+                    calmNodesInScope.add(id);
+                }
+            }
+        }
+    }
+    const calmCitedByFr = Math.min(calmNodesInScope.size, signals.fr_entries.filter(f => f.cited.length > 0).length);
+    const selfReportedNo = signals.coverage_rows.filter(r => r.status === 'NO').length;
+    return {
+        threats_in_scope: strideIdsInScope.size,
+        threats_covered_by_sr: [...threatsCitedBySr].filter(id => strideIdsInScope.has(id)).length,
+        calm_nodes_in_scope: calmNodesInScope.size,
+        calm_nodes_cited_by_fr: calmCitedByFr,
+        self_reported_no_count: selfReportedNo,
+    };
+}
+// ============================================================================
+// Combined score
+// ============================================================================
+function combineScore(archScore, secScore, citation) {
+    const threatCoverage = citation.threats_in_scope === 0
+        ? 1
+        : citation.threats_covered_by_sr / citation.threats_in_scope;
+    const calmCoverage = citation.calm_nodes_in_scope === 0
+        ? 1
+        : citation.calm_nodes_cited_by_fr / citation.calm_nodes_in_scope;
+    const noPenalty = Math.min(0.30, citation.self_reported_no_count * 0.05);
+    const citationScore = Math.max(0, harmonicMean(threatCoverage, calmCoverage) - noPenalty);
+    return 0.35 * archScore + 0.35 * secScore + 0.30 * citationScore;
+}
+function harmonicMean(a, b) {
+    if (a <= 0 || b <= 0) {
+        return 0;
+    }
+    return (2 * a * b) / (a + b);
+}
+function round4(n) {
+    return Math.round(n * 10000) / 10000;
+}

package/dist/runner/prd.d.ts

@@ -0,0 +1,28 @@
+export interface PrdOptions {
+    brief: unknown;
+    meshDir: string;
+    outputDir: string;
+    auditDir: string;
+    emitPrBodyPath?: string;
+    agentVersion: string;
+    anthropicApiKey?: string;
+    githubToken?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface PrdResult {
+    run_id: string;
+    topic: string;
+    artifact_path: string;
+    manifest_path: string;
+    audit_log_path: string;
+    chain_root_hash: string;
+    pr_body_path: string | null;
+    /** PASS / ITERATE / EXHAUSTED — the final verdict of verify_grounding. */
+    verdict: 'PASS' | 'ITERATE' | 'EXHAUSTED';
+    final_score: number;
+    iterations: number;
+    total_input_tokens: number;
+    total_output_tokens: number;
+    total_cost_usd: number;
+}
+export declare function runPrd(opts: PrdOptions): Promise<PrdResult>;