@maintainabilityai/research-runner 0.1.1

package/dist/runner/nodes/synthesis-archaeology-validator.d.ts

@@ -0,0 +1,22 @@
+/**
+ * synthesis-archaeology-validator — structural validator for the
+ * archaeology-path synthesis body.
+ *
+ * Mirrors synthesis-validator's shape (ValidationReport with citation_stats)
+ * but enforces the 9 canonical sections from
+ * `.caterpillar/prompts/research/synthesis-archaeology.md`:
+ *
+ *   1. Executive Summary
+ *   2. Repository Profile
+ *   3. Current Architecture
+ *   4. Gap Analysis            (G[N] entries with severity)
+ *   5. External Research Findings
+ *   6. Recommendations         (each cites ≥1 G[N] AND ≥1 grounding token)
+ *   7. Implementation Roadmap
+ *   8. Risk Factors
+ *   9. Untraced items          (REQUIRED — may say "None.")
+ */
+import type { ValidationReport } from './synthesis-validator';
+export declare const CANONICAL_ARCHAEOLOGY_SECTIONS: readonly ["Executive Summary", "Repository Profile", "Current Architecture", "Gap Analysis", "External Research Findings", "Recommendations", "Implementation Roadmap", "Risk Factors", "Untraced items"];
+export type CanonicalArchaeologySection = typeof CANONICAL_ARCHAEOLOGY_SECTIONS[number];
+export declare function validateArchaeologySynthesis(body: string): ValidationReport;

package/dist/runner/nodes/synthesis-archaeology-validator.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANONICAL_ARCHAEOLOGY_SECTIONS = void 0;
+exports.validateArchaeologySynthesis = validateArchaeologySynthesis;
+exports.CANONICAL_ARCHAEOLOGY_SECTIONS = [
+    'Executive Summary',
+    'Repository Profile',
+    'Current Architecture',
+    'Gap Analysis',
+    'External Research Findings',
+    'Recommendations',
+    'Implementation Roadmap',
+    'Risk Factors',
+    'Untraced items',
+];
+function validateArchaeologySynthesis(body) {
+    const errors = [];
+    const sectionsFound = extractH2Sections(body);
+    // Sections present in canonical order
+    for (let i = 0; i < exports.CANONICAL_ARCHAEOLOGY_SECTIONS.length; i++) {
+        const expected = exports.CANONICAL_ARCHAEOLOGY_SECTIONS[i];
+        if (sectionsFound[i] !== expected) {
+            errors.push(`Section #${i + 1} expected "## ${expected}" but found ${sectionsFound[i] ? `"## ${sectionsFound[i]}"` : '(missing)'}.`);
+        }
+    }
+    // Gap Analysis: at least one G[N] entry with severity
+    const gapBlock = extractSection(body, 'Gap Analysis');
+    const gapEntries = splitOnGapMarkers(gapBlock);
+    const gapIds = gapEntries.map(g => g.id);
+    for (const g of gapEntries) {
+        // `\b\*\*` fails between space and `*` (both non-word) — drop the boundary
+        // before `**` and require the inner word boundary instead.
+        if (!/\bSEVERITY\s*[:=]\s*(HIGH|MEDIUM|LOW)\b|\*\*(HIGH|MEDIUM|LOW)\*\*/i.test(g.body)) {
+            errors.push(`Gap G${g.id} is missing a severity tag (HIGH / MEDIUM / LOW).`);
+        }
+    }
+    if (gapEntries.length === 0 && sectionsFound.includes('Gap Analysis')) {
+        errors.push('Gap Analysis section has no `G[N]` entries.');
+    }
+    // Recommendations: each cites ≥1 G[N]
+    const recsBlock = extractSection(body, 'Recommendations');
+    const recLines = recsBlock.split('\n').filter(l => /^\s*(?:[-*]|\d+\.)\s+/.test(l));
+    let untracedRecommendations = 0;
+    for (const rec of recLines) {
+        if (!/\bG\d+\b/.test(rec)) {
+            untracedRecommendations += 1;
+        }
+    }
+    if (recLines.length > 0 && untracedRecommendations === recLines.length) {
+        errors.push(`All ${recLines.length} Recommendation(s) lack G[N] traceability.`);
+    }
+    else if (untracedRecommendations > 0) {
+        errors.push(`${untracedRecommendations} of ${recLines.length} Recommendation(s) lack G[N] traceability.`);
+    }
+    // Untraced items REQUIRED — even if empty (must say "None." or similar)
+    const untracedBlock = extractSection(body, 'Untraced items').trim();
+    if (untracedBlock.length === 0) {
+        errors.push('Untraced items section is empty — must explicitly say "None." when there are none.');
+    }
+    // Citation stats
+    // For archaeology, source_count = unique S[N] across External Research Findings + Risk Factors.
+    // The synthesis prompt also asks the LLM to cite OA[<file>] / OA[<module>] in narrative
+    // sections; we don't try to enforce those at the validator level (heuristic untraced count
+    // would be too noisy across short body paragraphs).
+    const sourceCitations = new Set([...body.matchAll(/\bS(\d+)\b/g)].map(m => m[1]));
+    const citation_stats = {
+        source_count: sourceCitations.size,
+        conclusion_count: 0, // archaeology synthesis doesn't have C[N]
+        recommendation_count: recLines.length,
+        underCitedConclusions: 0,
+        untracedRecommendations,
+        untraced_claims: 0,
+    };
+    return {
+        valid: errors.length === 0,
+        errors,
+        sectionsFound,
+        citation_stats,
+        // Expose archaeology-specific data for the orchestrator's audit + Hatter's Tag
+        ...(gapIds.length > 0 ? { archaeology: { gap_count: gapIds.length } } : {}),
+    };
+}
+// ============================================================================
+// Helpers (copy of the research-side helpers — kept local to avoid coupling)
+// ============================================================================
+function extractH2Sections(body) {
+    const out = [];
+    for (const line of body.split('\n')) {
+        const m = line.match(/^##\s+(.+?)\s*$/);
+        if (m) {
+            out.push(m[1].trim());
+        }
+    }
+    return out;
+}
+function extractSection(body, sectionName) {
+    const lines = body.split('\n');
+    let inSection = false;
+    const collected = [];
+    for (const line of lines) {
+        const h2 = line.match(/^##\s+(.+?)\s*$/);
+        if (h2) {
+            if (h2[1].trim() === sectionName) {
+                inSection = true;
+                continue;
+            }
+            if (inSection) {
+                break;
+            }
+        }
+        if (inSection) {
+            collected.push(line);
+        }
+    }
+    return collected.join('\n');
+}
+function splitOnGapMarkers(block) {
+    const markerRe = /^\s*(?:\*\*G(\d+)\*\*|###\s+G(\d+))(?=\s|$)/;
+    const lines = block.split('\n');
+    const entries = [];
+    for (const line of lines) {
+        const m = line.match(markerRe);
+        if (m) {
+            entries.push({ id: m[1] ?? m[2], body: [line] });
+        }
+        else if (entries.length > 0) {
+            entries[entries.length - 1].body.push(line);
+        }
+    }
+    return entries.map(e => ({ id: e.id, body: e.body.join('\n') }));
+}

package/dist/runner/nodes/synthesis-validator.d.ts

@@ -0,0 +1,51 @@
+/**
+ * synthesis-validator — pure structural validator for the markdown body
+ * produced by synthesize_report.
+ *
+ * Enforces the canonical 10-section structure defined in
+ * `.caterpillar/prompts/research/synthesis.md`. Returns a ValidationReport
+ * (pass/fail + reasons + per-section citation stats) the caller uses to:
+ *   - decide whether to retry the LLM with feedback
+ *   - populate ResearchDoc.citation_stats in the audit log
+ *
+ * Deliberately conservative: only checks structural rules the prompt was
+ * explicit about. Semantic checks (does this conclusion actually follow
+ * from its sources?) are left to the expert review nodes in the PRD phase.
+ */
+/** Sections required in this exact order. Drift fails validation. */
+export declare const CANONICAL_SECTIONS: readonly ["Source Premises", "Executive Summary", "Cross-Source Analysis", "Evidence Gaps", "Jobs-to-be-Done Analysis", "Patent Landscape", "Whitespace Analysis", "Formal Conclusions", "Recommendations", "References"];
+export type CanonicalSection = typeof CANONICAL_SECTIONS[number];
+export interface CitationStats {
+    source_count: number;
+    conclusion_count: number;
+    recommendation_count: number;
+    /** Conclusions with a confidence rating but fewer than 2 source citations (1 ok for LOW). */
+    underCitedConclusions: number;
+    /** Recommendations missing a `C[N]` reference. */
+    untracedRecommendations: number;
+    /** Top-level claims (sentences) in narrative sections with no `S[N]` citation. Heuristic. */
+    untraced_claims: number;
+}
+export interface ValidationReport {
+    valid: boolean;
+    /** Human-readable errors — fed back to the LLM on retry. */
+    errors: string[];
+    /** Sections found (in body order). */
+    sectionsFound: string[];
+    citation_stats: CitationStats;
+}
+/**
+ * Parse + validate a synthesised research-doc markdown body.
+ *
+ * Validation rules (each contributes one error string when violated):
+ *   1. Every CANONICAL_SECTION must appear as an H2.
+ *   2. The H2 sections must appear in CANONICAL order (no shuffling).
+ *   3. `Source Premises` must contain at least 1 `**S[N]**` entry.
+ *   4. Every `Formal Conclusion` (a `**C[N]**` line) must:
+ *      - carry a confidence label `**HIGH**` / `**MEDIUM**` / `**LOW**`,
+ *      - cite ≥2 `S[N]` (≥1 permitted only when confidence is `LOW`).
+ *   5. Every `Recommendation` line must reference at least one `C[N]`.
+ *
+ * Returns a ValidationReport with `valid: true` when no rule fails.
+ */
+export declare function validateSynthesis(body: string): ValidationReport;

package/dist/runner/nodes/synthesis-validator.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * synthesis-validator — pure structural validator for the markdown body
+ * produced by synthesize_report.
+ *
+ * Enforces the canonical 10-section structure defined in
+ * `.caterpillar/prompts/research/synthesis.md`. Returns a ValidationReport
+ * (pass/fail + reasons + per-section citation stats) the caller uses to:
+ *   - decide whether to retry the LLM with feedback
+ *   - populate ResearchDoc.citation_stats in the audit log
+ *
+ * Deliberately conservative: only checks structural rules the prompt was
+ * explicit about. Semantic checks (does this conclusion actually follow
+ * from its sources?) are left to the expert review nodes in the PRD phase.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANONICAL_SECTIONS = void 0;
+exports.validateSynthesis = validateSynthesis;
+/** Sections required in this exact order. Drift fails validation. */
+exports.CANONICAL_SECTIONS = [
+    'Source Premises',
+    'Executive Summary',
+    'Cross-Source Analysis',
+    'Evidence Gaps',
+    'Jobs-to-be-Done Analysis',
+    'Patent Landscape',
+    'Whitespace Analysis',
+    'Formal Conclusions',
+    'Recommendations',
+    'References',
+];
+/**
+ * Parse + validate a synthesised research-doc markdown body.
+ *
+ * Validation rules (each contributes one error string when violated):
+ *   1. Every CANONICAL_SECTION must appear as an H2.
+ *   2. The H2 sections must appear in CANONICAL order (no shuffling).
+ *   3. `Source Premises` must contain at least 1 `**S[N]**` entry.
+ *   4. Every `Formal Conclusion` (a `**C[N]**` line) must:
+ *      - carry a confidence label `**HIGH**` / `**MEDIUM**` / `**LOW**`,
+ *      - cite ≥2 `S[N]` (≥1 permitted only when confidence is `LOW`).
+ *   5. Every `Recommendation` line must reference at least one `C[N]`.
+ *
+ * Returns a ValidationReport with `valid: true` when no rule fails.
+ */
+function validateSynthesis(body) {
+    const errors = [];
+    const sectionsFound = extractH2Sections(body);
+    // Rule 1 + 2 combined: sections must be present in canonical order
+    for (let i = 0; i < exports.CANONICAL_SECTIONS.length; i++) {
+        const expected = exports.CANONICAL_SECTIONS[i];
+        if (sectionsFound[i] !== expected) {
+            errors.push(`Section #${i + 1} expected "## ${expected}" but found ${sectionsFound[i] ? `"## ${sectionsFound[i]}"` : '(missing)'}.`);
+            // One error per slot is enough — keep going so we report all drift in one shot.
+        }
+    }
+    // Rule 3: Source Premises has ≥1 entry
+    const sourceBlock = extractSection(body, 'Source Premises');
+    const sourceIds = [...sourceBlock.matchAll(/\*\*S(\d+)\*\*/g)].map(m => parseInt(m[1], 10));
+    const source_count = new Set(sourceIds).size;
+    if (source_count === 0) {
+        errors.push('Source Premises has no `**S[N]**` entries.');
+    }
+    // Rule 4: Formal Conclusions.
+    // Split the block on each `**C[N]**` (or `### C[N]`) marker — gives us one
+    // chunk per conclusion containing the statement + confidence + citations.
+    const conclusionsBlock = extractSection(body, 'Formal Conclusions');
+    const conclusionChunks = splitOnConclusionMarkers(conclusionsBlock);
+    const conclusion_count = conclusionChunks.length;
+    let underCitedConclusions = 0;
+    for (const { id, body: tail } of conclusionChunks) {
+        const confidenceMatch = tail.match(/\*\*(HIGH|MEDIUM|LOW)\*\*/);
+        if (!confidenceMatch) {
+            errors.push(`Conclusion C${id} is missing a confidence label (**HIGH** / **MEDIUM** / **LOW**).`);
+            underCitedConclusions += 1;
+            continue;
+        }
+        const confidence = confidenceMatch[1];
+        const cited = new Set([...tail.matchAll(/\bS(\d+)\b/g)].map(c => parseInt(c[1], 10)));
+        const minRequired = confidence === 'LOW' ? 1 : 2;
+        if (cited.size < minRequired) {
+            errors.push(`Conclusion C${id} (${confidence}) cites ${cited.size} source(s); requires ≥${minRequired}.`);
+            underCitedConclusions += 1;
+        }
+    }
+    // Rule 5: Recommendations
+    const recsBlock = extractSection(body, 'Recommendations');
+    // Treat each bullet (- or *) at the start of a line, or a numbered "1." as one recommendation.
+    const recLines = recsBlock.split('\n').filter(l => /^\s*(?:[-*]|\d+\.)\s+/.test(l));
+    const recommendation_count = recLines.length;
+    let untracedRecommendations = 0;
+    for (const rec of recLines) {
+        if (!/\bC\d+\b/.test(rec)) {
+            untracedRecommendations += 1;
+        }
+    }
+    if (recommendation_count > 0 && untracedRecommendations === recommendation_count) {
+        errors.push(`All ${recommendation_count} Recommendation(s) lack C[N] traceability.`);
+    }
+    else if (untracedRecommendations > 0) {
+        errors.push(`${untracedRecommendations} of ${recommendation_count} Recommendation(s) lack C[N] traceability.`);
+    }
+    // Heuristic untraced-claims count across narrative sections (not used as a hard fail signal).
+    const narrativeSections = ['Executive Summary', 'Cross-Source Analysis', 'Jobs-to-be-Done Analysis', 'Whitespace Analysis'];
+    let untraced_claims = 0;
+    for (const sec of narrativeSections) {
+        const block = extractSection(body, sec);
+        // Count sentences ending in . ? ! that contain neither S[N] nor C[N]
+        const sentences = block.match(/[^.!?\n]+[.!?]/g) ?? [];
+        for (const s of sentences) {
+            if (!/\b[SC]\d+\b/.test(s) && s.trim().length > 40) {
+                untraced_claims += 1;
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        sectionsFound,
+        citation_stats: {
+            source_count,
+            conclusion_count,
+            recommendation_count,
+            underCitedConclusions,
+            untracedRecommendations,
+            untraced_claims,
+        },
+    };
+}
+/** Pull H2 headings (one per `## Heading` line). Subsection H3+ headings are ignored. */
+function extractH2Sections(body) {
+    const out = [];
+    for (const line of body.split('\n')) {
+        const m = line.match(/^##\s+(.+?)\s*$/);
+        if (m) {
+            out.push(m[1].trim());
+        }
+    }
+    return out;
+}
+/**
+ * Walk the lines of a Formal Conclusions block and return one entry per
+ * `**C[N]**` (or `### C[N]`) marker. The chunk body is every line up to
+ * the next marker. Robust against multi-line conclusions and missing
+ * trailing newlines.
+ */
+function splitOnConclusionMarkers(block) {
+    // No \b after `**C1**` — `*` and the following space are both non-word, so
+    // \b is false there. Use an explicit space/EOL lookahead instead.
+    const markerRe = /^\s*(?:\*\*C(\d+)\*\*|###\s+C(\d+))(?=\s|$)/;
+    const lines = block.split('\n');
+    const entries = [];
+    for (const line of lines) {
+        const m = line.match(markerRe);
+        if (m) {
+            entries.push({ id: m[1] ?? m[2], body: [line] });
+        }
+        else if (entries.length > 0) {
+            entries[entries.length - 1].body.push(line);
+        }
+    }
+    return entries.map(e => ({ id: e.id, body: e.body.join('\n') }));
+}
+/** Slice the body for a single named H2 section (text up to the next H2 or EOF). */
+function extractSection(body, sectionName) {
+    const lines = body.split('\n');
+    let inSection = false;
+    const collected = [];
+    for (const line of lines) {
+        const h2 = line.match(/^##\s+(.+?)\s*$/);
+        if (h2) {
+            if (h2[1].trim() === sectionName) {
+                inSection = true;
+                continue;
+            }
+            if (inSection) {
+                break;
+            } // next H2 closes the section
+        }
+        if (inSection) {
+            collected.push(line);
+        }
+    }
+    return collected.join('\n');
+}

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

@@ -0,0 +1,84 @@
+/**
+ * synthesize_prd — LLM node.
+ *
+ * Loads `.caterpillar/prompts/prd/synthesis.md`, fills in brief +
+ * mesh-context + ranked-sources (carried over from the upstream research
+ * doc), calls Anthropic / GitHub Models, runs prd-validator on the body.
+ *
+ * Unlike research's synthesize_report, this node has TWO call modes:
+ *   - First iteration: standard prompt fill, no prior-review feedback
+ *   - Subsequent iterations: same prompt + a feedback prefix block
+ *     summarising the prior verify_grounding failure (CHANGES from
+ *     architecture_review + security_review) so the LLM knows what to fix
+ *
+ * Returns the validated PRD body + the structural signals
+ * verify_grounding needs, plus standard LLM telemetry.
+ */
+import type { LlmProvider, MeshContext, PrdBrief, RankedSource } from '../../schemas';
+import { type LoadedPrompt } from '../../mesh/prompt-loader';
+import { type PrdCitationSignals, type PrdValidationReport } from './prd-validator';
+/**
+ * GapFeedback composer surface — collected from all 4 reviewers (LLM + deterministic)
+ * at the end of each iteration that didn't PASS. Prepended to the next synthesis.
+ */
+export interface DeterministicFindings {
+    severity: 'PASS' | 'MINOR' | 'MAJOR';
+    invalid_citations: Array<{
+        where: string;
+        cite: string;
+        reason: string;
+    }>;
+    coverage_discrepancies: Array<{
+        premise: string;
+        claimed_status: string;
+        detail: string;
+    }>;
+}
+export interface PriorReviewFeedback {
+    iteration: number;
+    architecture: {
+        score: number;
+        severity: string;
+        changes: string[];
+    };
+    security: {
+        score: number;
+        severity: string;
+        changes: string[];
+    };
+    /** Deterministic findings — what citation-grep saw; usually the most actionable signal. */
+    det_architecture?: DeterministicFindings;
+    det_security?: DeterministicFindings;
+    /** |arch_score − sec_score| from the prior round; high values signal reconciliation needed. */
+    disagreement_delta?: number;
+}
+export interface SynthesizePrdOpts {
+    meshDir: string;
+    brief: PrdBrief;
+    meshContext: MeshContext;
+    /** Sources carried over from the research doc (R[N] in the PRD body). */
+    rankedSources: RankedSource[];
+    /** Provider routing — comes from brief.llm_provider unless overridden. */
+    provider?: LlmProvider;
+    anthropicApiKey?: string;
+    githubToken?: string;
+    /** Present on iteration ≥ 2 — carries the prior round's review CHANGES. */
+    priorFeedback?: PriorReviewFeedback;
+    fetchImpl?: typeof fetch;
+}
+export interface SynthesizePrdResult {
+    body_md: string;
+    prompt: LoadedPrompt;
+    validation: PrdValidationReport;
+    signals: PrdCitationSignals;
+    llm: {
+        provider: LlmProvider;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+        /** Number of LLM calls within this single iteration (1 happy, 2 on retry). */
+        attempts: number;
+    };
+}
+export declare function synthesizePrd(opts: SynthesizePrdOpts): Promise<SynthesizePrdResult>;

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

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.synthesizePrd = synthesizePrd;
+const llm_router_1 = require("../../llm/llm-router");
+const prompt_loader_1 = require("../../mesh/prompt-loader");
+const prd_validator_1 = require("./prd-validator");
+const MAX_TOKENS = 8000;
+async function synthesizePrd(opts) {
+    const provider = opts.provider ?? opts.brief.llm_provider;
+    const promptContext = buildPromptContext(opts.brief, opts.meshContext, opts.rankedSources);
+    const prompt = (0, prompt_loader_1.loadPrompt)({
+        meshDir: opts.meshDir,
+        packId: 'prd/synthesis',
+        context: promptContext,
+    });
+    const system = 'You write PRDs with strict section discipline and bidirectional traceability. Every Functional Requirement (FR-NN) cites at least one R[N] or E[N] premise. Every Security Requirement (SR-NN) cites at least one THR-NNN, A0X, or NIST-XX-NN identifier. The Coverage Analysis table includes a row for every premise. The 10 H2 sections 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 feedbackBlock = attempt === 1 && opts.priorFeedback
+            ? buildFeedbackBlock(opts.priorFeedback)
+            : '';
+        const validationBlock = attempt === 2 && lastReport
+            ? `\n\n---\n\nYour previous response failed structural validation:\n${lastReport.errors.map(e => `- ${e}`).join('\n')}\n\nRewrite the document. Fix EVERY error above. Maintain section order. Every FR-NN must cite ≥1 R[N] or E[N]; every SR-NN must cite ≥1 THR/A0X/NIST identifier; the Coverage Analysis table must include every premise.`
+            : '';
+        const userPrompt = `${feedbackBlock}${prompt.filled}${validationBlock}`;
+        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 = (0, prd_validator_1.validatePrd)(body);
+        if (report.valid) {
+            return {
+                body_md: body,
+                prompt,
+                validation: report,
+                signals: report.signals,
+                llm: { provider, model: lastModel, inputTokens: totalInput, outputTokens: totalOutput, costUsd: totalCost, attempts: attempt },
+            };
+        }
+        lastReport = report;
+    }
+    throw new Error(`synthesize_prd: structural validation failed after 2 attempts. Last errors: ${lastReport.errors.join('; ')}`);
+}
+function stripFences(raw) {
+    const trimmed = raw.trim();
+    const fenceMatch = trimmed.match(/^```(?:markdown|md)?\s*([\s\S]*?)```\s*$/);
+    return fenceMatch ? fenceMatch[1].trim() : trimmed;
+}
+/**
+ * Feedback block prepended on iteration 2+. Merges signals from all four
+ * reviewers — the two LLM experts (CHANGES list) AND the two deterministic
+ * reviewers (invalid citations + coverage discrepancies). The deterministic
+ * sections are most actionable: they name specific IDs the LLM must add /
+ * remove. Disagreement-delta is surfaced so the LLM can reconcile the two
+ * expert perspectives instead of just averaging them.
+ */
+function buildFeedbackBlock(feedback) {
+    const lines = [];
+    lines.push('# Prior Review Feedback (iteration ' + feedback.iteration + ')');
+    lines.push('');
+    lines.push('The previous PRD draft did not meet the grounding threshold. Apply every change below before re-emitting the PRD.');
+    lines.push('');
+    if (feedback.disagreement_delta !== undefined && feedback.disagreement_delta >= 0.2) {
+        lines.push(`## Reviewer Disagreement: ${feedback.disagreement_delta.toFixed(2)}`);
+        lines.push('');
+        lines.push('The architecture and security experts gave scores that diverged by ≥ 0.2. Reconcile their perspectives in this draft — explicitly address why one side scored higher.');
+        lines.push('');
+    }
+    // LLM expert CHANGES — qualitative guidance
+    lines.push(`## Architecture expert review (LLM, score ${feedback.architecture.score.toFixed(2)}, severity ${feedback.architecture.severity})`);
+    if (feedback.architecture.changes.length === 0) {
+        lines.push('- _no specific changes flagged_');
+    }
+    for (const c of feedback.architecture.changes) {
+        lines.push(`- ${c}`);
+    }
+    lines.push('');
+    lines.push(`## Security expert review (LLM, score ${feedback.security.score.toFixed(2)}, severity ${feedback.security.severity})`);
+    if (feedback.security.changes.length === 0) {
+        lines.push('- _no specific changes flagged_');
+    }
+    for (const c of feedback.security.changes) {
+        lines.push(`- ${c}`);
+    }
+    lines.push('');
+    // Deterministic findings — specific IDs to fix. Most actionable.
+    const det = (label, d) => {
+        if (!d || (d.invalid_citations.length === 0 && d.coverage_discrepancies.length === 0)) {
+            return [];
+        }
+        const out = [`## ${label} (deterministic citation grep, severity ${d.severity})`];
+        if (d.invalid_citations.length > 0) {
+            out.push('');
+            out.push('**Invalid citations — these IDs do not exist in the mesh and must be removed or replaced:**');
+            for (const c of d.invalid_citations) {
+                out.push(`- \`${c.where}\` cites \`${c.cite}\` — ${c.reason}`);
+            }
+        }
+        if (d.coverage_discrepancies.length > 0) {
+            out.push('');
+            out.push('**Coverage Analysis table discrepancies — fix the table or the body so they agree:**');
+            for (const x of d.coverage_discrepancies) {
+                out.push(`- Premise \`${x.premise}\`: ${x.detail}`);
+            }
+        }
+        out.push('');
+        return out;
+    };
+    for (const l of det('Architecture (deterministic)', feedback.det_architecture)) {
+        lines.push(l);
+    }
+    for (const l of det('Security (deterministic)', feedback.det_security)) {
+        lines.push(l);
+    }
+    lines.push('---');
+    lines.push('');
+    return lines.join('\n');
+}
+/** Build the dotted-key context the PRD synthesis prompt asks for. */
+function buildPromptContext(brief, mesh, rankedSources) {
+    // Premise IDs: R1..RN from the research doc's ranked sources;
+    // E1..EN come from mesh-extracted expert points + ask_experts answers.
+    // Phase 4 doesn't run ask_experts yet — E IDs come from the mesh BAR's
+    // STRIDE entries + ADRs + mesh_gaps as inferred expert input.
+    const meshExpertPoints = extractMeshExpertPoints(mesh);
+    return {
+        brief: {
+            topic: deriveTopic(brief),
+        },
+        scope: {
+            bar_id: brief.scope.id ?? '(portfolio scope)',
+        },
+        research_findings: rankedSources.map((s, i) => `R${i + 1}: ${s.title} — ${s.url} (provider=${s.provider}, salience=${s.salience_score})`).join('\n'),
+        mesh_expert_input: meshExpertPoints.length === 0
+            ? '(no expert input — BAR mesh artifacts are sparse)'
+            : meshExpertPoints.map((p, i) => `E${i + 1}: ${p}`).join('\n'),
+        clarifying_answers: '(none — ask_experts deferred to phase 4b)',
+        calm_endpoints: extractCalmEndpoints(mesh).join(', ') || '(none)',
+        stride_entries: extractThreatIds(mesh).join(', ') || '(none)',
+        nist_controls: '(none documented in mesh)',
+        owasp_in_scope: '(derived per threat at synthesis time)',
+    };
+}
+function deriveTopic(brief) {
+    if (brief.research_source.kind === 'pr') {
+        const m = brief.research_source.url.match(/\/pull\/(\d+)/);
+        return m ? `PRD from research PR #${m[1]}` : 'PRD (research source: PR)';
+    }
+    const base = brief.research_source.relative_path.split('/').pop()?.replace(/\.md$/, '') ?? 'topic';
+    return base.replace(/-/g, ' ');
+}
+function extractMeshExpertPoints(mesh) {
+    const out = [];
+    const bar = mesh.bar;
+    if (!bar) {
+        return out;
+    }
+    for (const adr of bar.adrs.slice(0, 6)) {
+        out.push(`ADR ${adr.id} (${adr.status}): ${adr.title}`);
+    }
+    for (const gap of bar.mesh_gaps) {
+        out.push(`mesh gap: ${gap}`);
+    }
+    return out;
+}
+function extractCalmEndpoints(mesh) {
+    const calm = mesh.bar?.calm_model;
+    if (!calm || typeof calm !== 'object') {
+        return [];
+    }
+    const nodes = calm.nodes;
+    if (!Array.isArray(nodes)) {
+        return [];
+    }
+    return nodes
+        .map(n => n['unique-id'])
+        .filter((id) => typeof id === 'string');
+}
+function extractThreatIds(mesh) {
+    const threats = mesh.bar?.threats;
+    if (!Array.isArray(threats)) {
+        return [];
+    }
+    return threats
+        .map(t => t.id)
+        .filter((id) => typeof id === 'string');
+}