feat(agent): semantic control mapping — embedding index + region->control retrieval (#215)

compliance-agent/src/controls/scan_triage.rs

@@ -16,9 +16,15 @@ use compliance_core::models::onboarding::ComplianceFramework;
 use compliance_core::AgentConfig;
 use control_map::ControlMap;
 
-use super::{ControlTriage, LlmControlJudge, OscalControlsProvider, TriageOutcome};
+use super::{
+    ControlIndex, ControlTriage, LlmControlJudge, OscalControlsProvider, SemanticControlChecker,
+    TriageOutcome,
+};
 use crate::llm::LlmClient;
 
+/// Nearest master controls judged per code region in the semantic pass.
+const SEMANTIC_TOP_K: usize = 5;
+
 /// Lines of context to read on each side of a finding's line.
 const REGION_WINDOW: usize = 6;
 
@@ -116,6 +122,103 @@ fn fetch_region(repo_path: &Path, file: &str, line: u32) -> Option<CandidateRegi
     })
 }
 
+/// Master-controls **semantic** pass: for each finding's code region, retrieve the
+/// top-K nearest master controls by embedding, have the grounded judge confirm,
+/// and stamp the confirmed control ids onto the finding — the scale path for the
+/// ~13.6k master-control corpus (which has no CWE to LUT on). Returns the number
+/// of findings that gained a master-control ref.
+///
+/// Opt-in: the orchestrator does not run this yet. It builds the control embedding
+/// index per call (embeds the whole corpus) — production should cache/persist that
+/// index rather than rebuild it each scan.
+pub async fn semantic_stamp_findings(
+    config: &AgentConfig,
+    llm: Arc<LlmClient>,
+    repo_path: &Path,
+    findings: &mut [Finding],
+) -> usize {
+    let Some(base_url) = config.breakpilot.base_url.clone() else {
+        return 0;
+    };
+    let provider = OscalControlsProvider::new(
+        reqwest::Client::new(),
+        base_url,
+        config.breakpilot.token.clone(),
+        &config.breakpilot.snapshot_dir,
+    );
+    let doc = match provider.load_master_controls().await {
+        Ok(d) => d,
+        Err(e) => {
+            tracing::warn!(error = %e, "master-controls catalog unavailable; skipping semantic pass");
+            return 0;
+        }
+    };
+    let specs: Vec<ControlCheckSpec> = doc
+        .to_controls()
+        .into_iter()
+        .map(|c| ControlCheckSpec {
+            control_id: c.id,
+            title: c.title,
+            requirement: c.text,
+            default_cwe: None,
+            severity: Severity::Medium,
+        })
+        .collect();
+    let index = match ControlIndex::build(&llm, specs).await {
+        Ok(i) if !i.is_empty() => i,
+        Ok(_) => return 0,
+        Err(e) => {
+            tracing::warn!(error = %e, "failed to embed master-controls corpus");
+            return 0;
+        }
+    };
+    let checker = SemanticControlChecker::new(LlmControlJudge::new(llm.clone()));
+
+    let mut tagged = 0;
+    for finding in findings.iter_mut() {
+        if finding.status == FindingStatus::FalsePositive {
+            continue;
+        }
+        let (Some(file), Some(line)) = (finding.file_path.clone(), finding.line_number) else {
+            continue;
+        };
+        let Some(region) = fetch_region(repo_path, &file, line) else {
+            continue;
+        };
+        let region_emb = match llm.embed(vec![region.content.clone()]).await {
+            Ok(mut embs) => match embs.pop() {
+                Some(v) => v,
+                None => continue,
+            },
+            Err(e) => {
+                tracing::warn!(error = %e, "region embed failed; skipping finding");
+                continue;
+            }
+        };
+        let confirmed = checker
+            .check(
+                &index,
+                &region,
+                &region_emb,
+                SEMANTIC_TOP_K,
+                &finding.repo_id,
+            )
+            .await;
+        let before = finding.control_refs.len();
+        for f in confirmed {
+            for cref in f.control_refs {
+                if !finding.control_refs.contains(&cref) {
+                    finding.control_refs.push(cref);
+                }
+            }
+        }
+        if finding.control_refs.len() > before {
+            tagged += 1;
+        }
+    }
+    tagged
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;