@maintainabilityai/research-runner 0.1.1

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

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runExpertReview = runExpertReview;
+exports.parseReviewResponse = parseReviewResponse;
+const llm_router_1 = require("../../llm/llm-router");
+const prompt_loader_1 = require("../../mesh/prompt-loader");
+const MAX_TOKENS = 1500;
+async function runExpertReview(opts) {
+    const packId = opts.expert === 'architecture'
+        ? 'prd/architecture-review'
+        : 'prd/security-review';
+    const promptContext = buildPromptContext(opts.expert, opts.prdBody, opts.meshContext, opts.iteration, opts.priorReview);
+    const prompt = (0, prompt_loader_1.loadPrompt)({ meshDir: opts.meshDir, packId, context: promptContext });
+    const system = opts.expert === 'architecture'
+        ? 'You are a senior architect reviewing a PRD for grounding against the CALM model. Output strictly in the SCORE / SEVERITY / COVERED / MISSING / CHANGES format — no prose before or after. SEVERITY must be one of PASS / MINOR / MAJOR / BLOCKING.'
+        : 'You are a senior application-security engineer reviewing a PRD for STRIDE / OWASP / NIST coverage. Output strictly in the SCORE / SEVERITY / COVERED / MISSING / CHANGES format — no prose before or after. SEVERITY must be one of PASS / MINOR / MAJOR / BLOCKING.';
+    let totalInput = 0;
+    let totalOutput = 0;
+    let totalCost = 0;
+    let lastModel = '';
+    let lastError = null;
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        const userPrompt = attempt === 1
+            ? prompt.filled
+            : `${prompt.filled}\n\n---\n\nYour previous response could not be parsed:\n${lastError}\n\nReturn EXACTLY this 5-field structured-text format, no prose:\nSCORE: <0..1>\nSEVERITY: <PASS|MINOR|MAJOR|BLOCKING>\nCOVERED: <ids>\nMISSING: <ids>\nCHANGES:\n- <change>`;
+        const result = await (0, llm_router_1.callLlm)({
+            provider: opts.provider,
+            tier: 'plan', // reviews are tighter than synthesis — cheaper tier is fine
+            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 parsed = parseReviewResponse(result.text, opts.expert, opts.iteration);
+        if (parsed.success) {
+            return {
+                review: parsed.data,
+                prompt,
+                llm: { provider: opts.provider, model: lastModel, inputTokens: totalInput, outputTokens: totalOutput, costUsd: totalCost, attempts: attempt },
+            };
+        }
+        lastError = parsed.error;
+    }
+    throw new Error(`expert_review (${opts.expert}): could not parse SCORE/SEVERITY/COVERED/MISSING/CHANGES after 2 attempts. Last error: ${lastError}`);
+}
+// ============================================================================
+// Response parsing
+// ============================================================================
+const VALID_SEVERITY = new Set(['PASS', 'MINOR', 'MAJOR', 'BLOCKING']);
+function parseReviewResponse(raw, expert, iteration) {
+    const text = stripFences(raw.trim());
+    const score = parseScore(text);
+    if (score === null) {
+        return { success: false, error: 'SCORE: <float> line missing or unparseable' };
+    }
+    const severity = parseSeverity(text);
+    if (!severity) {
+        return { success: false, error: 'SEVERITY must be one of PASS / MINOR / MAJOR / BLOCKING' };
+    }
+    const covered_ids = parseIdList(text, /^COVERED:\s*(.*)$/im);
+    const missing_ids = parseIdList(text, /^MISSING:\s*(.*)$/im);
+    const changes = parseChangesBlock(text);
+    return {
+        success: true,
+        data: {
+            expert,
+            iteration,
+            score,
+            severity,
+            covered_ids,
+            missing_ids,
+            changes,
+        },
+    };
+}
+function parseScore(text) {
+    const m = text.match(/^SCORE:\s*([0-9.]+)\s*$/im);
+    if (!m) {
+        return null;
+    }
+    const n = parseFloat(m[1]);
+    if (!Number.isFinite(n)) {
+        return null;
+    }
+    return Math.max(0, Math.min(1, n));
+}
+function parseSeverity(text) {
+    const m = text.match(/^SEVERITY:\s*([A-Z]+)\s*$/im);
+    if (!m) {
+        return null;
+    }
+    const sev = m[1].toUpperCase();
+    return VALID_SEVERITY.has(sev) ? sev : null;
+}
+function parseIdList(text, re) {
+    const m = text.match(re);
+    if (!m) {
+        return [];
+    }
+    return m[1]
+        .split(',')
+        .map(s => s.trim())
+        .filter(s => s.length > 0 && s !== '-' && s.toLowerCase() !== 'none');
+}
+function parseChangesBlock(text) {
+    const idx = text.search(/^CHANGES:\s*$/im);
+    if (idx === -1) {
+        return [];
+    }
+    const tail = text.slice(idx);
+    const lines = tail.split('\n').slice(1);
+    const changes = [];
+    for (const line of lines) {
+        const m = line.match(/^\s*[-*]\s+(.+)$/);
+        if (m) {
+            changes.push(m[1].trim());
+        }
+        else if (line.trim().length > 0 && !line.match(/^[A-Z]+:\s/)) {
+            // Continuation lines for a multi-line change item
+            if (changes.length > 0) {
+                changes[changes.length - 1] += ' ' + line.trim();
+            }
+        }
+        else if (line.match(/^[A-Z_]+:\s/)) {
+            // Hit the next header field — stop
+            break;
+        }
+    }
+    return changes;
+}
+function stripFences(s) {
+    const fenceMatch = s.match(/^```\s*([\s\S]*?)```\s*$/);
+    return fenceMatch ? fenceMatch[1].trim() : s;
+}
+// ============================================================================
+// Prompt context
+// ============================================================================
+function buildPromptContext(expert, prdBody, meshContext, iteration, priorReview) {
+    const ctx = {
+        prd_doc: prdBody,
+        iteration,
+        prior_review: priorReview
+            ? `Previous iteration (${priorReview.iteration}) — score ${priorReview.score.toFixed(2)}, severity ${priorReview.severity}. CHANGES requested:\n${priorReview.changes.map(c => `- ${c}`).join('\n')}`
+            : '(first iteration — no prior review)',
+    };
+    if (expert === 'architecture') {
+        ctx['mesh.bar.calm_summary'] = summarizeCalm(meshContext);
+        ctx.calm_node_ids = extractCalmNodeIds(meshContext).join(', ') || '(none)';
+        ctx.adrs_in_scope = (meshContext.bar?.adrs ?? []).map(a => a.id).join(', ') || '(none)';
+    }
+    else {
+        ctx.stride_entries = extractStrideIds(meshContext).join(', ') || '(none)';
+        ctx.owasp_in_scope = '(derived from STRIDE entries — see PRD body for current claims)';
+        ctx.nist_controls = '(see policies/nist-800-53-controls.yaml in mesh)';
+    }
+    return ctx;
+}
+function summarizeCalm(mesh) {
+    const calm = mesh.bar?.calm_model;
+    if (!calm || typeof calm !== 'object') {
+        return '(no CALM model loaded)';
+    }
+    const nodes = calm.nodes;
+    if (!Array.isArray(nodes)) {
+        return '(empty CALM model)';
+    }
+    const lines = [`${nodes.length} node(s):`];
+    for (const n of nodes.slice(0, 12)) {
+        const o = n;
+        lines.push(`  - ${o['unique-id']} (${o['node-type'] ?? 'unknown'}) — ${o.name ?? ''}`);
+    }
+    return lines.join('\n');
+}
+function extractCalmNodeIds(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 => String(n['unique-id'] ?? '')).filter(Boolean);
+}
+function extractStrideIds(mesh) {
+    const threats = mesh.bar?.threats;
+    if (!Array.isArray(threats)) {
+        return [];
+    }
+    return threats.map(t => String(t.id ?? '')).filter(Boolean);
+}

package/dist/runner/nodes/gap-analysis.d.ts

@@ -0,0 +1,48 @@
+import type { LlmProvider, RankedSource, ResearchBrief } from '../../schemas';
+export type GapSignalKind = 'low_source_diversity' | 'topic_uncovered' | 'low_provider_overlap';
+export interface GapSignal {
+    kind: GapSignalKind;
+    /** Short human-readable explanation for the audit log. */
+    evidence: string;
+}
+export interface ShouldRunGapAnalysisOpts {
+    brief: ResearchBrief;
+    rankedSources: RankedSource[];
+    /** Trigger when total < this. Default 5. */
+    minSources?: number;
+    /** Trigger when one provider holds > this fraction. Default 0.85. */
+    dominantProviderRatio?: number;
+}
+/**
+ * Pure deterministic trigger check. Returns the gap signals found; an
+ * empty array means "do not run gap_analysis".
+ */
+export declare function detectGapSignals(opts: ShouldRunGapAnalysisOpts): GapSignal[];
+export interface RunGapAnalysisOpts {
+    meshDir: string;
+    brief: ResearchBrief;
+    rankedSources: RankedSource[];
+    signals: GapSignal[];
+    provider: LlmProvider;
+    anthropicApiKey?: string;
+    githubToken?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface GapAnalysisResult {
+    /** Exactly 3 follow-up web queries the LLM produced. */
+    followUpQueries: string[];
+    /** Prompt-pack telemetry for the audit log. */
+    prompt: {
+        packPath: string;
+        packSha256: string;
+    };
+    llm: {
+        provider: LlmProvider;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+        attempts: number;
+    };
+}
+export declare function runGapAnalysis(opts: RunGapAnalysisOpts): Promise<GapAnalysisResult>;

package/dist/runner/nodes/gap-analysis.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectGapSignals = detectGapSignals;
+exports.runGapAnalysis = runGapAnalysis;
+/**
+ * gap_analysis — pure trigger + LLM hop, bounded one-shot.
+ *
+ * After the first-pass dedupe, this module:
+ *   1) Decides whether to fire at all (pure, deterministic).
+ *   2) If yes, asks the LLM for exactly 3 follow-up web queries.
+ *
+ * Trigger conditions (any one fires):
+ *   - low_source_diversity:  fewer than `minSources` total ranked sources
+ *     across the whole first pass.
+ *   - topic_uncovered:       at least one topic keyword from the brief is
+ *     mentioned in zero result titles/excerpts.
+ *   - low_provider_overlap:  most sources came from a single provider
+ *     (the synthesis prompt's Cross-Source Analysis falls apart when
+ *     there's no cross-source angle).
+ *
+ * The bounded loop (one extra round of tavily, no further) is enforced by
+ * the orchestrator — not this node. We return the queries; the caller
+ * decides what to do with them.
+ */
+const zod_1 = require("zod");
+const llm_router_1 = require("../../llm/llm-router");
+const prompt_loader_1 = require("../../mesh/prompt-loader");
+const FollowUpQueriesSchema = zod_1.z.array(zod_1.z.string().min(3)).length(3);
+/**
+ * Pure deterministic trigger check. Returns the gap signals found; an
+ * empty array means "do not run gap_analysis".
+ */
+function detectGapSignals(opts) {
+    const signals = [];
+    const minSources = opts.minSources ?? 5;
+    const dominantRatio = opts.dominantProviderRatio ?? 0.85;
+    const { rankedSources, brief } = opts;
+    if (rankedSources.length < minSources) {
+        signals.push({
+            kind: 'low_source_diversity',
+            evidence: `only ${rankedSources.length} ranked source(s); threshold ${minSources}`,
+        });
+    }
+    if (rankedSources.length > 0) {
+        const byProvider = new Map();
+        for (const r of rankedSources) {
+            byProvider.set(r.provider, (byProvider.get(r.provider) ?? 0) + 1);
+        }
+        const maxCount = Math.max(...byProvider.values());
+        const ratio = maxCount / rankedSources.length;
+        if (ratio > dominantRatio && rankedSources.length >= 4) {
+            const dominant = [...byProvider.entries()].find(([, n]) => n === maxCount)?.[0];
+            signals.push({
+                kind: 'low_provider_overlap',
+                evidence: `${(ratio * 100).toFixed(0)}% of sources from ${dominant}; no cross-source signal`,
+            });
+        }
+    }
+    // Topic-uncoverage heuristic: split brief.topic into 3+ char keywords,
+    // check each appears in at least one result title or excerpt. If a
+    // keyword appears nowhere, that's a topic-uncovered signal.
+    const keywords = extractTopicKeywords(brief.topic);
+    const haystack = rankedSources.map(r => `${r.title} ${r.excerpt}`).join(' ').toLowerCase();
+    const uncovered = keywords.filter(k => !haystack.includes(k));
+    if (uncovered.length > 0) {
+        signals.push({
+            kind: 'topic_uncovered',
+            evidence: `brief keyword(s) absent from any result: ${uncovered.slice(0, 5).join(', ')}`,
+        });
+    }
+    return signals;
+}
+function extractTopicKeywords(topic) {
+    const stop = new Set(['the', 'and', 'for', 'with', 'from', 'into', 'about', 'over', 'after', 'before']);
+    return topic
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(w => w.length >= 4 && !stop.has(w))
+        .slice(0, 10);
+}
+async function runGapAnalysis(opts) {
+    const promptContext = {
+        brief: { topic: opts.brief.topic },
+        first_pass: {
+            summary: `${opts.rankedSources.length} ranked source(s); top providers: ${topProviderSummary(opts.rankedSources)}`,
+            gaps: opts.signals.map(s => `- ${s.kind}: ${s.evidence}`).join('\n'),
+        },
+    };
+    const prompt = (0, prompt_loader_1.loadPrompt)({
+        meshDir: opts.meshDir,
+        packId: 'research/gap-analysis',
+        context: promptContext,
+    });
+    const system = 'You output a SINGLE JSON array of exactly 3 strings. No prose before or after, no markdown fence. The first character of your response MUST be `[`.';
+    let totalInput = 0;
+    let totalOutput = 0;
+    let totalCost = 0;
+    let lastModel = '';
+    let lastError = null;
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        const userPrompt = attempt === 1
+            ? prompt.filled
+            : `${prompt.filled}\n\n---\n\nYour previous response failed validation:\n${lastError}\n\nReturn a SINGLE JSON array of exactly 3 strings (each a follow-up web query). No prose, no markdown.`;
+        const result = await (0, llm_router_1.callLlm)({
+            provider: opts.provider,
+            tier: 'plan', // cheap tier; this is structural follow-up
+            anthropicApiKey: opts.anthropicApiKey,
+            githubToken: opts.githubToken,
+            system,
+            prompt: userPrompt,
+            maxTokens: 1000,
+            fetchImpl: opts.fetchImpl,
+        });
+        totalInput += result.inputTokens;
+        totalOutput += result.outputTokens;
+        totalCost += result.costUsd;
+        lastModel = result.model;
+        const parsed = parseFollowUpQueries(result.text);
+        if (parsed.success) {
+            return {
+                followUpQueries: parsed.data,
+                prompt: { packPath: prompt.packPath, packSha256: prompt.packSha256 },
+                llm: { provider: opts.provider, model: lastModel, inputTokens: totalInput, outputTokens: totalOutput, costUsd: totalCost, attempts: attempt },
+            };
+        }
+        lastError = parsed.error;
+    }
+    throw new Error(`gap_analysis: LLM output failed validation after 2 attempts. Last error: ${lastError}`);
+}
+function parseFollowUpQueries(raw) {
+    const trimmed = raw.trim();
+    const fenceMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const candidate = fenceMatch ? fenceMatch[1].trim() : trimmed;
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(candidate);
+    }
+    catch (e) {
+        return { success: false, error: `not valid JSON: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    const result = FollowUpQueriesSchema.safeParse(parsedJson);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, error: result.error.issues.map(i => `${i.path.join('.') || '<root>'}: ${i.message}`).join('; ') };
+}
+function topProviderSummary(sources) {
+    const counts = new Map();
+    for (const s of sources) {
+        counts.set(s.provider, (counts.get(s.provider) ?? 0) + 1);
+    }
+    return [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([p, n]) => `${p}=${n}`).join(', ');
+}

package/dist/runner/nodes/generate-prd-manifest.d.ts

@@ -0,0 +1,53 @@
+/**
+ * generate_prd_manifest — pure node.
+ *
+ * Takes the validated PRD body + grounding result + brief, produces the
+ * PrdManifest JSON that lives alongside the published PRD markdown.
+ *
+ * The manifest is what Cheshire's `spec-ready-handler.yml` reads in target
+ * code repos to generate an RCTRO implementation issue. Keeping it
+ * separate from the PRD body means downstream consumers (Cheshire, audit
+ * dashboards) can read structured data without re-parsing markdown.
+ */
+import type { GroundingBlock, MeshContext, PrdBrief, PrdManifest, ImpactedBar } from '../../schemas';
+import type { PrdCitationSignals } from './prd-validator';
+export interface GenerateManifestOpts {
+    runId: string;
+    brief: PrdBrief;
+    meshContext: MeshContext;
+    prdBody: string;
+    signals: PrdCitationSignals;
+    grounding: GroundingBlock;
+    threshold: number;
+}
+/**
+ * Build the PrdManifest. Endpoints come from regex-extracted FR-NN entries
+ * that mention an HTTP-method + path; security requirements come straight
+ * from the validator's parsed SR entries.
+ *
+ * impacted_bars + target_repos come from computeImpactedBars() — see that
+ * function for the HIGH/LOW classification logic. target_repos is the
+ * union of HIGH-confidence BARs' repos (LOW bars surface only as footer
+ * mentions in the landing-issues, never as auto-created issues).
+ */
+export declare function generatePrdManifest(opts: GenerateManifestOpts): PrdManifest;
+/**
+ * Classify every BAR in scope as HIGH or LOW confidence based on whether
+ * the PRD's citations touch a CALM node the BAR owns or a threat the BAR
+ * declared.
+ *
+ * Inputs:
+ *   - endpoints[].calm_node     — referenced CALM ids
+ *   - security_requirements[].citations.THR-*  — referenced threat ids
+ *
+ * Per BAR:
+ *   - own_calm_nodes ∩ referenced_calm_nodes ≠ ∅  → HIGH (endpoint hit)
+ *   - own_threat_ids ∩ referenced_threat_ids ≠ ∅  → HIGH (threat hit)
+ *   - otherwise (BAR is in the platform but no citation overlap) → LOW
+ *
+ * At BAR scope, only that one BAR is in scope and it is always HIGH (the
+ * PRD is about it by definition; the linked_repos are the target). At
+ * platform scope, the current BAR is null and every sibling BAR is
+ * classified. Portfolio scope falls back to the placeholder.
+ */
+export declare function computeImpactedBars(mesh: MeshContext, endpoints: PrdManifest['endpoints'], securityRequirements: PrdManifest['security_requirements']): ImpactedBar[];

package/dist/runner/nodes/generate-prd-manifest.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePrdManifest = generatePrdManifest;
+exports.computeImpactedBars = computeImpactedBars;
+/**
+ * Build the PrdManifest. Endpoints come from regex-extracted FR-NN entries
+ * that mention an HTTP-method + path; security requirements come straight
+ * from the validator's parsed SR entries.
+ *
+ * impacted_bars + target_repos come from computeImpactedBars() — see that
+ * function for the HIGH/LOW classification logic. target_repos is the
+ * union of HIGH-confidence BARs' repos (LOW bars surface only as footer
+ * mentions in the landing-issues, never as auto-created issues).
+ */
+function generatePrdManifest(opts) {
+    const topic = derivePrdTopic(opts.brief, opts.prdBody);
+    const endpoints = extractEndpoints(opts.prdBody);
+    const security_requirements = opts.signals.sr_entries.map(sr => ({
+        id: sr.id,
+        // The schema's citation regex accepts THR-* / A0* / NIST-XX-N — we filter
+        // to those before passing through (FR-side IDs would fail validation).
+        citations: sr.cited.filter(c => /^(?:THR-\d+|A\d{2}|NIST-[A-Z]{2}-\d+)$/.test(c)),
+    }));
+    const impacted_bars = computeImpactedBars(opts.meshContext, endpoints, security_requirements);
+    const target_repos = deriveTargetRepos(impacted_bars, opts.meshContext);
+    return {
+        run_id: opts.runId,
+        prd_topic: topic,
+        mesh_sha: opts.meshContext.mesh_sha,
+        target_repos,
+        impacted_bars,
+        endpoints,
+        security_requirements,
+        grounding: {
+            final_score: opts.grounding.final_score,
+            threshold: opts.threshold,
+            iterations: opts.grounding.final_iteration,
+            passed: opts.grounding.passed,
+        },
+    };
+}
+/**
+ * Classify every BAR in scope as HIGH or LOW confidence based on whether
+ * the PRD's citations touch a CALM node the BAR owns or a threat the BAR
+ * declared.
+ *
+ * Inputs:
+ *   - endpoints[].calm_node     — referenced CALM ids
+ *   - security_requirements[].citations.THR-*  — referenced threat ids
+ *
+ * Per BAR:
+ *   - own_calm_nodes ∩ referenced_calm_nodes ≠ ∅  → HIGH (endpoint hit)
+ *   - own_threat_ids ∩ referenced_threat_ids ≠ ∅  → HIGH (threat hit)
+ *   - otherwise (BAR is in the platform but no citation overlap) → LOW
+ *
+ * At BAR scope, only that one BAR is in scope and it is always HIGH (the
+ * PRD is about it by definition; the linked_repos are the target). At
+ * platform scope, the current BAR is null and every sibling BAR is
+ * classified. Portfolio scope falls back to the placeholder.
+ */
+function computeImpactedBars(mesh, endpoints, securityRequirements) {
+    const referencedCalm = new Set(endpoints.map(e => e.calm_node).filter(n => n && n !== 'unknown'));
+    const referencedThreats = new Set();
+    for (const sr of securityRequirements) {
+        for (const c of sr.citations) {
+            if (c.startsWith('THR-')) {
+                referencedThreats.add(c);
+            }
+        }
+    }
+    // BAR scope: only the current BAR; trivially HIGH (PRD is about it).
+    if (mesh.bar) {
+        const reasoning = endpoints.length > 0 || securityRequirements.length > 0
+            ? `PRD scope is BAR ${mesh.bar.bar_id}; covers ${endpoints.length} endpoint(s), ${securityRequirements.length} security requirement(s).`
+            : `PRD scope is BAR ${mesh.bar.bar_id}.`;
+        return [{
+                bar_id: mesh.bar.bar_id,
+                repos: uniqueOwnerRepos(mesh.bar.linked_repos),
+                confidence: 'high',
+                reasoning,
+            }];
+    }
+    // Platform scope: classify each sibling. (When mesh.bar is null AND
+    // mesh.platform is set, the PRD is platform-scoped.)
+    const siblings = mesh.platform?.sibling_bars ?? [];
+    if (siblings.length === 0) {
+        return [];
+    }
+    return siblings.map(sib => {
+        const calmHits = sib.calm_node_ids.filter(id => referencedCalm.has(id));
+        const threatHits = sib.threat_ids.filter(id => referencedThreats.has(id));
+        if (calmHits.length > 0 || threatHits.length > 0) {
+            const parts = [];
+            if (calmHits.length > 0) {
+                parts.push(`owns CALM node${calmHits.length > 1 ? 's' : ''} ${calmHits.map(n => `\`${n}\``).join(', ')} referenced by ${endpoints.filter(e => calmHits.includes(e.calm_node)).map(e => e.fr_id).join(', ')}`);
+            }
+            if (threatHits.length > 0) {
+                parts.push(`owns threat${threatHits.length > 1 ? 's' : ''} ${threatHits.map(t => `\`${t}\``).join(', ')} cited by security requirements`);
+            }
+            return {
+                bar_id: sib.bar_id,
+                repos: uniqueOwnerRepos(sib.linked_repos),
+                confidence: 'high',
+                reasoning: parts.join('; '),
+            };
+        }
+        return {
+            bar_id: sib.bar_id,
+            repos: uniqueOwnerRepos(sib.linked_repos),
+            confidence: 'low',
+            reasoning: 'No CALM nodes or threats from this BAR are cited by the PRD. Listed as a low-confidence reference in case shared infra / downstream effects apply.',
+        };
+    });
+}
+/**
+ * target_repos = the union of HIGH-confidence BARs' repos. LOW BARs are
+ * intentionally excluded from auto-issue creation; they surface only as
+ * footer mentions in the HIGH BARs' landing-issues.
+ *
+ * Fallbacks (no HIGH bars + no impacted_bars at all): keep the manifest
+ * valid by emitting the BAR-id placeholder so the user notices something
+ * is misconfigured.
+ */
+function deriveTargetRepos(impactedBars, mesh) {
+    const highRepos = impactedBars
+        .filter(b => b.confidence === 'high')
+        .flatMap(b => b.repos);
+    if (highRepos.length > 0) {
+        return uniqueOwnerRepos(highRepos);
+    }
+    // Edge case: a PRD that didn't pull in any sibling-BAR citations and
+    // has no BAR scope. Surface a placeholder so the manifest still
+    // validates and the run log shows the user that nothing matched.
+    if (mesh.bar) {
+        return [`mesh/${mesh.bar.bar_id.toLowerCase()}`];
+    }
+    return ['placeholder/repo'];
+}
+function derivePrdTopic(brief, body) {
+    // Prefer the body's H1 if present; falls back to a research-source-derived label.
+    const h1 = body.match(/^#\s+(.+?)\s*$/m);
+    if (h1) {
+        return h1[1].trim().slice(0, 200);
+    }
+    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, ' ');
+}
+/**
+ * Extract endpoint declarations from FR-NN entries.
+ * Looks for HTTP-method + path within each FR's body lines.
+ */
+function extractEndpoints(body) {
+    const fnSection = sliceSection(body, 'Functional Requirements with Traceability');
+    if (!fnSection) {
+        return [];
+    }
+    const out = [];
+    const lines = fnSection.split('\n');
+    let currentFr = null;
+    let currentCalmNode = null;
+    for (const line of lines) {
+        const frMatch = line.match(/\b(FR-\d+)\b/);
+        if (frMatch) {
+            currentFr = frMatch[1];
+            currentCalmNode = null;
+        }
+        const calmHint = line.match(/CALM\s+node[:\s]+([\w-]+)/i);
+        if (calmHint) {
+            currentCalmNode = calmHint[1];
+        }
+        const epMatch = line.match(/\b(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s+(\/[\w/{}:.-]*)/);
+        if (epMatch && currentFr) {
+            out.push({
+                signature: `${epMatch[1]} ${epMatch[2]}`,
+                calm_node: currentCalmNode ?? 'unknown',
+                fr_id: currentFr,
+            });
+        }
+    }
+    return out;
+}
+function sliceSection(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.length === 0 ? null : collected.join('\n');
+}
+function uniqueOwnerRepos(list) {
+    return [...new Set(list)];
+}

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

@@ -0,0 +1,12 @@
+import type { ProviderResult } from '../../search/provider-result';
+import type { QueryEnvelope } from './tavily-search';
+export interface HackerNewsSearchNodeOpts {
+    queries: string[];
+    hitsPerQuery?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface HackerNewsSearchNodeResult {
+    envelopes: QueryEnvelope[];
+    results: ProviderResult[];
+}
+export declare function runHackerNewsSearch(opts: HackerNewsSearchNodeOpts): Promise<HackerNewsSearchNodeResult>;