heron-ai 0.2.2 → 0.4.0

package/dist/src/report/templates.js

@@ -1,30 +1,52 @@
-/** Filter out interview/orchestration platforms that aren't real business systems */
-function isBusinessSystem(s) {
-    const id = s.systemId.toLowerCase();
-    if (/\bheron\b/.test(id))
-        return false;
-    if (/internal\s*(orchestrat|api|platform)/.test(id))
-        return false;
-    if (/interview\s*(platform|endpoint|api)/.test(id))
-        return false;
-    if (/audit\s*(platform|endpoint|api)/.test(id))
-        return false;
-    // Platform session token with no real scopes = orchestration layer
-    if (/platform.?session.?token/i.test(id) && s.scopesRequested.length === 0)
-        return false;
-    return true;
+import { isProvided, UNKNOWN_PLACEHOLDER } from '../util/provided.js';
+import { isBusinessSystem } from '../util/systems.js';
+// ─── AAP-43 P1 #5: overall regulatory status ──────────────────────────────
+/**
+ * Reduce all activated framework flags into a single status label + gap
+ * counter. Replaces the prior EU/US/UK jurisdiction matrix which couldn't
+ * vary without US/UK frameworks in the OSS registry.
+ *
+ * Labels (descending severity):
+ *   - "Action Required"      — at least one action-required flag
+ *   - "Needs Clarification"  — at least one clarification-needed flag
+ *   - "Review"               — at least one warning-level flag
+ *   - "Not Triggered"        — no activated framework flags
+ */
+function summarizeOverallStatus(c) {
+    const all = (c.all ?? []);
+    if (all.length === 0)
+        return 'Not Triggered';
+    let label;
+    if (all.some(f => f.severity === 'action-required'))
+        label = 'Action Required';
+    else if (all.some(f => f.severity === 'clarification-needed'))
+        label = 'Needs Clarification';
+    else if (all.some(f => f.severity === 'warning'))
+        label = 'Review';
+    else
+        label = 'Not Triggered';
+    const mandatoryGaps = all.filter(f => f.tier === 'mandatory' && f.severity !== 'info').length;
+    const voluntaryGaps = all.filter(f => f.tier === 'voluntary' && f.severity !== 'info').length;
+    const parts = [];
+    if (mandatoryGaps > 0)
+        parts.push(`${mandatoryGaps} mandatory-framework gap${mandatoryGaps === 1 ? '' : 's'}`);
+    if (voluntaryGaps > 0)
+        parts.push(`${voluntaryGaps} voluntary-framework gap${voluntaryGaps === 1 ? '' : 's'}`);
+    const suffix = parts.length > 0 ? ` (${parts.join(', ')})` : '';
+    return `${label}${suffix}`;
 }
+// isBusinessSystem lives in src/util/systems.ts (shared with analyzer + mapper).
 export function renderMarkdownReport(report) {
     const sections = [
         renderHeader(report),
         renderScopeAndMethodology(report),
         renderSummary(report),
         renderAgentProfile(report),
-        renderFindings(report.risks),
+        renderFindings(report.risks, report.compliance),
         renderSystems(report.systems),
         renderPositiveFindings(report),
         renderVerdict(report),
-        report.regulatoryCompliance ? renderRegulatoryCompliance(report.regulatoryCompliance) : null,
+        report.compliance ? renderRegulatoryCompliance(report.compliance, report) : null,
         report.dataQuality ? renderDataQuality(report.dataQuality) : null,
         renderTranscript(report.transcript),
         renderDisclaimer(),
@@ -33,30 +55,25 @@ export function renderMarkdownReport(report) {
 }
 // ─── Header ──────────────────────────────────────────────────────────────────
 function renderHeader(report) {
-    const riskIcon = report.overallRiskLevel === 'critical' || report.overallRiskLevel === 'high' ? '!!' : '';
+    // Reviewer feedback (2026-04-25): the prior `!!` exclamation marker on
+    // HIGH/CRITICAL headers ("Risk Level: HIGH !!") was called out as
+    // "not a serious-document tone" — CISOs do not want excitement in audit
+    // headers. The `**Risk Level**: HIGH` label itself is already strong;
+    // the riskIcon adds nothing and undercuts credibility. Dropped.
     const dqPart = report.dataQuality ? ` | **Data Quality**: ${report.dataQuality.score}/100` : '';
-    // Regulatory one-liner
+    // AAP-43 P1 #5: single overall regulatory status label (replaces
+    // EU/US/UK matrix). The matrix implied we'd analyzed each jurisdiction,
+    // but we don't know the deployer's jurisdiction and only EU-mandatory
+    // frameworks are in OSS scope (see AAP-42). A single label + gap counter
+    // is honest: "here is the highest unresolved severity across activated
+    // frameworks, and how many mandatory vs voluntary gaps there are."
     let regLine = '';
-    if (report.regulatoryCompliance) {
-        const rc = report.regulatoryCompliance;
-        const regParts = [];
-        const summarizeJurisdiction = (flags) => {
-            if (flags.some(f => f.severity === 'action-required'))
-                return 'Action Required';
-            if (flags.some(f => f.severity === 'clarification-needed'))
-                return 'Needs Clarification';
-            if (flags.some(f => f.severity === 'warning'))
-                return 'Review';
-            return 'Clear';
-        };
-        regParts.push(`EU: ${summarizeJurisdiction(rc.eu)}`);
-        regParts.push(`US: ${summarizeJurisdiction(rc.us)}`);
-        regParts.push(`UK: ${summarizeJurisdiction(rc.uk)}`);
-        regLine = `\n**Regulatory**: ${regParts.join(' | ')}`;
+    if (report.compliance) {
+        regLine = `\n**Regulatory Status**: ${summarizeOverallStatus(report.compliance)}`;
     }
     return `# Agent Access Audit Report
 
-**Generated**: ${report.metadata.date} | **Agent**: ${report.metadata.target} | **Risk Level**: ${report.overallRiskLevel.toUpperCase()} ${riskIcon}${dqPart}${regLine}`;
+**Generated**: ${report.metadata.date} | **Agent**: ${report.metadata.target} | **Risk Level**: ${report.overallRiskLevel.toUpperCase()}${dqPart}${regLine}`;
 }
 // ─── Scope & Methodology ────────────────────────────────────────────────────
 function renderScopeAndMethodology(report) {
@@ -120,9 +137,17 @@ function renderSummary(report) {
     const dashboard = `| Risk | Systems | Findings |
 |------|---------|----------|
 | **${report.overallRiskLevel.toUpperCase()}** | ${systemCount} | ${findingsParts.join(', ')} |`;
+    let methodology = '';
+    if (report.compliance) {
+        const c = report.compliance;
+        const activated = (c.frameworksActivated ?? []);
+        const names = activated.map(id => frameworkShortName(id)).filter(Boolean);
+        const fwList = names.length > 0 ? names.join(', ') : 'see Regulatory Compliance section';
+        methodology = `\n\n> **Risk methodology** anchored to ${names.length} frameworks: ${fwList}. Mapping version: \`${c.mappingVersion}\`.`;
+    }
     return `## Executive Summary
 
-${dashboard}
+${dashboard}${methodology}
 
 ${report.summary}`;
 }
@@ -131,12 +156,12 @@ function renderAgentProfile(report) {
     const lines = [`- **Purpose**: ${report.agentPurpose}`];
     if (report.agentTrigger)
         lines.push(`- **Trigger**: ${report.agentTrigger}`);
-    if (report.agentOwner && report.agentOwner !== 'NOT PROVIDED') {
+    if (isProvided(report.agentOwner)) {
         lines.push(`- **Owner**: ${report.agentOwner}`);
     }
     // Frequency from first system if available
     const freq = report.systems[0]?.frequencyAndVolume;
-    if (freq && freq !== 'NOT PROVIDED')
+    if (isProvided(freq))
         lines.push(`- **Frequency**: ${freq}`);
     return `## Agent Profile
 
@@ -179,26 +204,32 @@ function renderSystemCard(sys) {
     const rows = [];
     const risk = computeSystemRisk(sys);
     // Scopes
-    const scopes = sys.scopesRequested.filter(s => s !== 'NOT PROVIDED');
-    rows.push(`| **Scopes granted** | ${scopes.length > 0 ? scopes.join(', ') : '*NOT PROVIDED*'} |`);
-    const needed = sys.scopesNeeded.filter(s => s !== 'NOT PROVIDED');
+    const scopes = sys.scopesRequested.filter(isProvided);
+    rows.push(`| **Scopes granted** | ${scopes.length > 0 ? scopes.join(', ') : `*${UNKNOWN_PLACEHOLDER}*`} |`);
+    const needed = sys.scopesNeeded.filter(isProvided);
     if (needed.length > 0) {
         rows.push(`| **Scopes needed** | ${needed.join(', ')} |`);
     }
-    const excessive = sys.scopesDelta;
+    const excessive = sys.scopesDelta.filter(isProvided);
     if (excessive.length > 0) {
         rows.push(`| **Excessive** | ${excessive.join(', ')} |`);
     }
     // Data sensitivity
-    if (sys.dataSensitivity && sys.dataSensitivity !== 'NOT PROVIDED') {
+    if (isProvided(sys.dataSensitivity)) {
         rows.push(`| **Data** | ${sys.dataSensitivity} |`);
     }
+    else {
+        rows.push(`| **Data** | *${UNKNOWN_PLACEHOLDER}* |`);
+    }
     // Blast radius
     rows.push(`| **Blast radius** | ${sys.blastRadius} |`);
     // Frequency
-    if (sys.frequencyAndVolume && sys.frequencyAndVolume !== 'NOT PROVIDED') {
+    if (isProvided(sys.frequencyAndVolume)) {
         rows.push(`| **Frequency** | ${sys.frequencyAndVolume} |`);
     }
+    else {
+        rows.push(`| **Frequency** | *${UNKNOWN_PLACEHOLDER}* |`);
+    }
     // Write operations — inline in card
     if (sys.writeOperations.length > 0) {
         const writesSummary = sys.writeOperations.map(w => {
@@ -214,20 +245,87 @@ function renderSystemCard(sys) {
 ${rows.join('\n')}`;
 }
 // ─── Findings ───────────────────────────────────────────────────────────────
-function renderFindings(risks) {
-    const allRisks = [...risks];
-    const sorted = allRisks
-        .sort((a, b) => severityOrder(b.severity) - severityOrder(a.severity));
-    const rows = sorted.map((r, i) => {
+/**
+ * Infer which compliance finding type best matches a risk by keyword matching
+ * on the risk's title and description. Returns the top-matching finding type
+ * or undefined if no strong match.
+ */
+function inferFindingType(risk) {
+    const text = `${risk.title} ${risk.description}`.toLowerCase();
+    if (/permission|scope|access.?control|excessive|least.?privilege|oauth/i.test(text))
+        return 'excessive-access';
+    if (/write|irreversible|delete|create|modify|append/i.test(text))
+        return 'write-risk';
+    if (/pii|personal.?data|sensitive|privacy|data.?protection/i.test(text))
+        return 'sensitive-data';
+    if (/scope.?creep|purpose.?limit|beyond.*need|unnecessary/i.test(text))
+        return 'scope-creep';
+    if (/classif|decision|scor|rank|profil|bias|discriminat/i.test(text))
+        return 'decisions-about-people';
+    if (/regulat|compliance|health|sector/i.test(text))
+        return 'regulatory-flags';
+    return undefined;
+}
+/**
+ * Get framework basis string for a finding type from the compliance flags.
+ * Returns top 3 mandatory framework controls, formatted as "GDPR Art. 25, EU AI Act Art. 10".
+ */
+function getFrameworkBasis(findingType, compliance) {
+    if (!compliance)
+        return '—';
+    const flags = compliance.all.filter((f) => f.triggeredBy === findingType && f.tier === 'mandatory');
+    if (flags.length === 0) {
+        // Try voluntary if no mandatory
+        const volFlags = compliance.all.filter((f) => f.triggeredBy === findingType);
+        if (volFlags.length === 0)
+            return '—';
+        return volFlags.slice(0, 3).map(f => `${f.frameworkId === 'eu-ai-act' ? 'EU AI Act' : f.framework.split(' — ')[0]}`).join(', ');
+    }
+    // Show top 3 mandatory, framework name + first control ID
+    return flags.slice(0, 3).map(f => {
+        const name = f.frameworkId === 'eu-ai-act' ? 'EU AI Act' : f.framework.split(' — ')[0];
+        const ctrl = (f.controlIds ?? [])[0] ?? '';
+        return ctrl ? `${name} ${ctrl}` : name;
+    }).join(', ');
+}
+function renderFindings(risks, compliance) {
+    if (risks.length === 0) {
+        return `## Findings\n\n_No risks identified._`;
+    }
+    const sorted = [...risks].sort((a, b) => severityOrder(b.severity) - severityOrder(a.severity));
+    const renderRow = (r, i) => {
         const id = `HERON-${String(i + 1).padStart(3, '0')}`;
+        const findingType = inferFindingType(r);
+        const basis = findingType ? getFrameworkBasis(findingType, compliance) : '—';
         const remediation = r.mitigation ?? '—';
-        return `| ${id} | ${r.severity.toUpperCase()} | ${r.title} | ${r.description} | ${remediation} |`;
-    }).join('\n');
+        return `| ${id} | ${r.severity.toUpperCase()} | ${basis} | ${r.title} | ${r.description} | ${remediation} |`;
+    };
+    const tableHeader = `| ID | Severity | Framework Basis | Finding | Description | Recommendation |
+|----|----------|-----------------|---------|-------------|----------------|`;
+    // AAP-43 P2 #7: Top-N triage. A flat 4+ finding table reads as "everything
+    // is equal weight." A senior auditor triages: here's the real issue, and
+    // here's the long tail. Split at 3; fold the rest into a collapsed section
+    // so readers still have access without being buried.
+    if (sorted.length <= 3) {
+        const rows = sorted.map(renderRow).join('\n');
+        return `## Findings\n\n${tableHeader}\n${rows}`;
+    }
+    const top = sorted.slice(0, 3).map(renderRow).join('\n');
+    const rest = sorted.slice(3).map((r, i) => renderRow(r, i + 3)).join('\n');
     return `## Findings
 
-| ID | Severity | Finding | Description | Recommendation |
-|----|----------|---------|-------------|----------------|
-${rows}`;
+### Top 3 Findings
+
+${tableHeader}
+${top}
+
+<details>
+<summary><strong>Additional findings (${sorted.length - 3})</strong></summary>
+
+${tableHeader}
+${rest}
+
+</details>`;
 }
 // ─── Positive Findings ─────────────────────────────────────────────────────
 function renderPositiveFindings(report) {
@@ -239,8 +337,23 @@ function renderPositiveFindings(report) {
         positives.push('All write operations are reversible');
     }
     // No excessive scopes
+    // Reviewer feedback (2026-04-25): a single report had both
+    // "No excessive permissions detected" AND a HIGH "Broad Google OAuth
+    // write scope exceeds stated single-sheet/single-folder need" finding —
+    // a direct internal contradiction. Root cause: the LLM put the broad-
+    // scope finding into `risks` (with a HIGH severity) but did not populate
+    // `scopesDelta`, so the structural counter said zero excessive scopes.
+    // Gate the positive on BOTH: zero scopesDelta entries AND no high-
+    // severity risk that the finding-type inferrer classifies as access /
+    // excessive-permissions / scope-creep.
     const totalExcessive = systems.reduce((n, s) => n + s.scopesDelta.length, 0);
-    if (totalExcessive === 0 && systems.length > 0) {
+    const hasAccessRisk = report.risks.some((r) => {
+        if (r.severity !== 'high' && r.severity !== 'critical')
+            return false;
+        const t = inferFindingType(r);
+        return t === 'excessive-access' || t === 'scope-creep';
+    });
+    if (totalExcessive === 0 && systems.length > 0 && !hasAccessRisk) {
         positives.push('No excessive permissions detected — follows least-privilege principle');
     }
     // Limited blast radius
@@ -290,14 +403,14 @@ function renderVerdict(report) {
         if (!isBusinessSystem(sys))
             continue;
         for (const scope of sys.scopesDelta) {
-            if (scope !== 'NOT PROVIDED') {
+            if (isProvided(scope)) {
                 if (!excessiveBySystem.has(sys.systemId))
                     excessiveBySystem.set(sys.systemId, []);
                 excessiveBySystem.get(sys.systemId).push(scope);
             }
         }
         for (const scope of sys.scopesNeeded) {
-            if (!sys.scopesRequested.includes(scope) && scope !== 'NOT PROVIDED') {
+            if (!sys.scopesRequested.includes(scope) && isProvided(scope)) {
                 if (!missingBySystem.has(sys.systemId))
                     missingBySystem.set(sys.systemId, []);
                 missingBySystem.get(sys.systemId).push(scope);
@@ -337,36 +450,275 @@ ${items}
 
 </details>`;
 }
-// ─── Regulatory Compliance ──────────────────────────────────────────────────
-function renderRegulatoryCompliance(compliance) {
-    const renderFlags = (flags) => {
-        if (flags.length === 0)
-            return 'No specific flags identified.';
-        return flags.map(f => {
-            const labels = {
-                'action-required': ' `ACTION REQUIRED`',
-                'warning': ' `REVIEW`',
-                'clarification-needed': ' `NEEDS CLARIFICATION`',
-            };
-            const label = labels[f.severity] ?? '';
-            return `- **${f.framework}**${label}\n  ${f.description}`;
-        }).join('\n\n');
+const CATEGORIES = [
+    { key: 'privacy', title: 'Privacy' },
+    { key: 'ip', title: 'IP' },
+    { key: 'consumer-protection', title: 'Consumer Protection' },
+    { key: 'sector-specific', title: 'Sector-Specific' },
+];
+// ─── Applicability Summary Table ─────────────────────────────────────────
+/** Human-readable descriptions for why a framework didn't fire. */
+const NOT_TRIGGERED_REASONS = {
+    'gdpr': 'No personal data signals detected',
+    'eu-ai-act': 'No applicable signals detected',
+};
+/** Short applicability condition for mandatory frameworks that DID fire. */
+const APPLICABILITY_CONDITIONS = {
+    'gdpr': 'If you serve EU data subjects',
+    'eu-ai-act': 'If AI placed on EU market or outputs used in EU',
+};
+/** Map finding types to human-readable gap descriptions. */
+const GAP_LABELS = {
+    'excessive-access': 'Excessive permissions',
+    'write-risk': 'Write operation risks',
+    'sensitive-data': 'Data handling',
+    'scope-creep': 'Scope exceeds purpose',
+    'decisions-about-people': 'Automated decision-making',
+    'regulatory-flags': 'Regulatory concerns',
+};
+/** Excluded from gap counting — always fires as methodology anchor, not a real gap. */
+const GAP_EXCLUDED = new Set(['risk-score']);
+function getGaps(frameworkId, allFlags) {
+    const flags = allFlags.filter(f => f.frameworkId === frameworkId && !GAP_EXCLUDED.has(f.triggeredBy));
+    // Also exclude decisions-about-people when it says "No decisions" (impact = none)
+    const meaningful = flags.filter(f => !(f.triggeredBy === 'decisions-about-people' && /no decisions about people/i.test(f.description)));
+    const uniqueTypes = [...new Set(meaningful.map(f => f.triggeredBy))];
+    return uniqueTypes.map(t => GAP_LABELS[t] ?? t);
+}
+function formatGaps(gaps) {
+    if (gaps.length === 0)
+        return { status: '✅ No gaps', details: '—' };
+    return {
+        status: `⚠️ ${gaps.length} gap${gaps.length > 1 ? 's' : ''}`,
+        details: gaps.join(', '),
     };
-    return `## Regulatory Compliance
-
-> This section highlights potential regulatory implications based on interview data. It is advisory — consult qualified legal counsel for compliance decisions.
-
-### EU (EU AI Act + GDPR)
-
-${renderFlags(compliance.eu)}
-
-### US (SOC 2 + State AI Laws)
+}
+function renderApplicabilitySummary(c) {
+    const activated = new Set(c.frameworksActivated ?? []);
+    const allFlags = (c.all ?? []);
+    const mandatoryFrameworks = [
+        { id: 'eu-ai-act', name: 'EU AI Act' },
+        { id: 'gdpr', name: 'GDPR' },
+    ];
+    const voluntaryFrameworks = [
+        { id: 'iso-42001', name: 'ISO/IEC 42001' },
+        { id: 'aiuc-1', name: 'AIUC-1 (Q2-2026)' },
+        { id: 'nist-ai-rmf', name: 'NIST AI RMF' },
+    ];
+    // EU AI Act classification scope label — single line replaces the prior
+    // two-entry split (`eu-ai-act` + `eu-ai-act-high-risk`).
+    const euClassification = c.euAiActClassification;
+    const mandatoryRows = mandatoryFrameworks.map(fw => {
+        const isActive = activated.has(fw.id);
+        if (!isActive) {
+            const reason = NOT_TRIGGERED_REASONS[fw.id] ?? 'No matching signals';
+            return `| ${fw.name} | ✅ Not applicable | ${reason} |`;
+        }
+        const gaps = getGaps(fw.id, allFlags);
+        let displayName = fw.name;
+        if (fw.id === 'eu-ai-act' && euClassification) {
+            const cls = euClassification.classification;
+            if (cls === 'high-risk' && euClassification.annexIIICategories.length > 0) {
+                displayName = `${fw.name} — High-Risk (Annex III ${euClassification.annexIIICategories.join(', ')})`;
+            }
+            else if (cls === 'limited') {
+                displayName = `${fw.name} — Limited-Risk (Art. 50 transparency)`;
+            }
+            else if (cls === 'prohibited') {
+                displayName = `${fw.name} — Prohibited Practice`;
+            }
+        }
+        if (gaps.length > 0) {
+            const condition = APPLICABILITY_CONDITIONS[fw.id] ?? '';
+            return `| ${displayName} | ⚠️ ${gaps.length} gap${gaps.length > 1 ? 's' : ''} | ${gaps.join(', ')} — ${condition} |`;
+        }
+        const condition = APPLICABILITY_CONDITIONS[fw.id] ?? 'Check applicability';
+        return `| ${displayName} | ⚠️ Check | ${condition} |`;
+    });
+    const voluntaryRows = voluntaryFrameworks.map(fw => {
+        const gaps = getGaps(fw.id, allFlags);
+        const { status, details } = formatGaps(gaps);
+        return `| ${fw.name} | ${status} | ${details} |`;
+    });
+    return `### Applicability Summary
 
-${renderFlags(compliance.us)}
+| Framework | Status | Gaps Found |
+|-----------|--------|------------|
+| **Mandatory Law** | | |
+${mandatoryRows.join('\n')}
+| **Voluntary Frameworks** | | |
+${voluntaryRows.join('\n')}`;
+}
+// ─── Finding-first detail (replaces framework-first tier sections) ────────
+/**
+ * Build agent-specific gap description from actual report data.
+ * Falls back to generic text if no specific context available.
+ */
+function buildGapDescription(findingType, report) {
+    const systems = report?.systems?.filter(isBusinessSystem) ?? [];
+    const systemNames = systems.map(s => s.systemId).join(', ');
+    const excessiveScopes = systems.flatMap(s => s.scopesDelta?.map(d => `${s.systemId}: ${d}`) ?? []);
+    const writes = systems.flatMap(s => s.writeOperations?.map(w => `${w.operation} → ${w.target}`) ?? []);
+    const hasIrreversible = systems.some(s => s.writeOperations?.some(w => !w.reversible));
+    const dataSensitivities = [...new Set(systems.map(s => s.dataSensitivity).filter(Boolean))];
+    const decisionDetails = report?.decisionMakingDetails ?? '';
+    switch (findingType) {
+        case 'excessive-access':
+            if (excessiveScopes.length > 0) {
+                return `Agent holds permissions beyond stated need on ${systems.length} system(s). Excessive scopes detected: ${excessiveScopes.join('; ')}. Narrow each to the minimum required scope.`;
+            }
+            return `Agent holds permissions beyond stated need on ${systemNames || 'connected systems'}. Review and narrow scopes to the minimum required (least-privilege).`;
+        case 'write-risk':
+            if (writes.length > 0) {
+                const qualifier = hasIrreversible ? 'including irreversible operations' : 'all reported as reversible';
+                return `Agent performs ${writes.length} write operation(s) (${qualifier}): ${writes.join('; ')}. Require approval, monitoring, and rollback paths for high-impact operations.`;
+            }
+            return 'Write operations detected that can affect users or downstream systems. Require approval, monitoring, and rollback paths.';
+        case 'sensitive-data':
+            if (dataSensitivities.length > 0) {
+                return `Agent processes ${dataSensitivities.join(', ')} data across ${systemNames || 'connected systems'}. Ensure lawful basis under GDPR Art. 6, data minimization (Art. 5(1)(c)), and breach-readiness (Art. 33).`;
+            }
+            return 'Agent processes personal data. Ensure lawful basis, data minimization, and breach-readiness.';
+        case 'scope-creep':
+            return `Requested scopes on ${systemNames || 'one or more systems'} exceed what is needed for the stated purpose. Review purpose-limitation (GDPR Art. 5(1)(b)) and change-management process.`;
+        case 'decisions-about-people':
+            if (decisionDetails) {
+                return `Agent makes or influences automated decisions affecting individuals: "${decisionDetails.slice(0, 150)}". Requires human oversight, contestability, transparency, and data-subject rights (GDPR Art. 22).`;
+            }
+            return 'Agent makes or influences automated decisions affecting individuals. Requires human oversight, contestability, transparency, and data-subject rights.';
+        case 'regulatory-flags':
+            return 'Agent may operate in a regulated domain. Clarify the agent\'s domain to determine sector-specific obligations.';
+        default:
+            return '';
+    }
+}
+/** Short framework display names for the "Affects" line. */
+function frameworkShortName(id) {
+    const names = {
+        'eu-ai-act': 'EU AI Act',
+        'gdpr': 'GDPR',
+        'iso-42001': 'ISO 42001',
+        'aiuc-1': 'AIUC-1 (Q2-2026)',
+        'nist-ai-rmf': 'NIST AI RMF',
+    };
+    return names[id] ?? id;
+}
+function renderFindingFirstDetail(c, report) {
+    const allFlags = (c.all ?? []);
+    // Group flags by finding type (triggeredBy)
+    const byFinding = new Map();
+    for (const f of allFlags) {
+        if (GAP_EXCLUDED.has(f.triggeredBy))
+            continue;
+        if (f.triggeredBy === 'decisions-about-people' && /no decisions about people/i.test(f.description))
+            continue;
+        const arr = byFinding.get(f.triggeredBy) ?? [];
+        arr.push(f);
+        byFinding.set(f.triggeredBy, arr);
+    }
+    if (byFinding.size === 0) {
+        return `### Compliance Detail\n\n_No compliance gaps identified from current signals._\n`;
+    }
+    let out = `### Compliance Detail\n\n`;
+    for (const [findingType, flags] of byFinding) {
+        const label = GAP_LABELS[findingType] ?? findingType;
+        const description = buildGapDescription(findingType, report);
+        // Group controls by framework for the "Affects" line.
+        // Reviewer feedback (2026-04-25): the prior "+N more" truncation
+        // ("AIUC-1 (A001, A002, A005, +1 more)") hides the very citations the
+        // report is asserting — in an audit deliverable, you don't redact
+        // your evidence. The earlier AAP-43 P2 #9 cap (3 per framework) was
+        // motivated by readability, not by citation hygiene. With the
+        // table-layout: fixed + overflow-wrap CSS now in place, long control
+        // lists wrap cleanly inside their cells, so we show the full list.
+        const byFramework = new Map();
+        for (const f of flags) {
+            const fwName = frameworkShortName(f.frameworkId);
+            const existing = byFramework.get(fwName) ?? [];
+            for (const ctrl of (f.controlIds ?? [])) {
+                if (!existing.includes(ctrl))
+                    existing.push(ctrl);
+            }
+            byFramework.set(fwName, existing);
+        }
+        const affectsParts = [...byFramework.entries()].map(([fw, ctrls]) => ctrls.length === 0 ? fw : `${fw} (${ctrls.join(', ')})`);
+        out += `#### ${label}\n\n`;
+        out += `${description}\n\n`;
+        out += `**Affects:** ${affectsParts.join(' · ')}\n\n`;
+    }
+    return out;
+}
+// ─── Obligations Requiring Further Review ─────────────────────────────────
+function renderObligationsChecklist(c, report) {
+    const activated = new Set(c.frameworksActivated ?? []);
+    const rows = [];
+    // AAP-43 P1 #3: GDPR obligations are signal-gated, not dumped as a 14-row
+    // boilerplate. Each row requires an explicit signal; if no PII/decisions/
+    // transfer signals fire, the table is skipped entirely.
+    const hasGdpr = activated.has('gdpr');
+    const signals = c.signals;
+    if (hasGdpr && signals) {
+        // ── PII-driven obligations ──────────────────────────────────────────
+        if (signals.hasPII) {
+            rows.push({ obligation: 'GDPR Art. 6', action: 'Decide and document WHY you are allowed to process this data (e.g. legitimate business interest — must document a balancing test)' });
+            rows.push({ obligation: 'GDPR Art. 13/14', action: 'Tell people you are collecting their data: what, why, how long, and their rights' });
+            rows.push({ obligation: 'GDPR Art. 15', action: 'Be ready to show someone all data you hold on them if they ask' });
+            rows.push({ obligation: 'GDPR Art. 17', action: "Be ready to delete someone's data from all systems if they ask" });
+            rows.push({ obligation: 'GDPR Art. 30', action: 'Keep a written log of what personal data you process, why, and who has access' });
+            rows.push({ obligation: 'GDPR Art. 5(1)(e)', action: 'Set rules for how long you keep data — then actually delete it on schedule' });
+        }
+        // ── Profiling / automated decisions ─────────────────────────────────
+        if (signals.hasDecisionsAboutPeople) {
+            rows.push({ obligation: 'GDPR Art. 21', action: 'Let people opt out of being profiled for sales/marketing — you must stop if they object' });
+        }
+        // ── Processor contracts ─────────────────────────────────────────────
+        if (signals.hasPII && signals.hasExternalProcessors) {
+            rows.push({ obligation: 'GDPR Art. 28', action: 'Sign data processing contracts with every service you send data to (Google, Apify, etc.)' });
+        }
+        // ── DPIA: large-scale OR decisions OR sensitive PII ─────────────────
+        if (signals.hasLargeScaleProcessing || signals.hasDecisionsAboutPeople || signals.hasSensitivePII) {
+            rows.push({ obligation: 'GDPR Art. 35', action: 'Do a privacy impact assessment before going live (large-scale / profiling / sensitive data → likely required)' });
+        }
+        // ── International transfer ──────────────────────────────────────────
+        if (signals.hasPII && signals.hasInternationalTransfer) {
+            rows.push({ obligation: 'GDPR Arts. 44-49', action: 'Data leaves the EU (e.g. to US-based Google/Apify) — you need a legal basis for that transfer (SCCs, adequacy decision, etc.)' });
+        }
+        // ── Art. 22 automated-decisions safeguard ───────────────────────────
+        if (signals.hasDecisionsAboutPeople) {
+            rows.push({ obligation: 'GDPR Art. 22', action: 'AI makes decisions about people: ensure a human can review, people can contest, and the logic is explainable' });
+        }
+    }
+    // Always applicable — baseline operational obligations
+    rows.push({ obligation: 'Credentials', action: 'Store API keys/tokens in a secrets manager (not in code or env files), rotate them regularly' });
+    rows.push({ obligation: 'Platform ToS', action: 'Check you are not violating the rules of LinkedIn, Google, or other connected services (scraping, rate limits, usage policies)' });
+    rows.push({ obligation: 'Incident response', action: 'Have a plan: if data leaks, who do you notify and within what timeframe? (EU: 72 hours to regulator)' });
+    if (rows.length === 0)
+        return '';
+    const tableRows = rows.map(r => `| ${r.obligation} | ${r.action} |`).join('\n');
+    return `### Obligations Requiring Further Review
 
-### UK (UK GDPR + ICO Guidance)
+The following cannot be assessed from this interview alone — the deployer must address independently:
 
-${renderFlags(compliance.uk)}`;
+| Obligation | Action Required |
+|------------|-----------------|
+${tableRows}`;
+}
+export function renderStructuredCompliance(c, report) {
+    return [
+        `## Regulatory Compliance`,
+        ``,
+        `### Methodology`,
+        ``,
+        `Findings are anchored to EU AI Act 2024/1689, GDPR 2016/679, ISO/IEC 42001 (AI management system), AIUC-1 (agent-native standard, pinned to Q2-2026 release 2026-04-15), and NIST AI RMF 1.0 (US-origin voluntary risk-management framework; GOVERN/MAP/MEASURE/MANAGE). Mapping version: \`${c.mappingVersion}\`. EU AI Act is a single framework entry; Annex III high-risk obligations are surfaced as a classification scope label on that entry (replacing the prior two-entry split). Control mappings are indicative — they show which framework clauses a finding typically activates and do not constitute legal advice.`,
+        ``,
+        renderApplicabilitySummary(c),
+        ``,
+        renderFindingFirstDetail(c, report),
+        renderObligationsChecklist(c, report),
+    ].join('\n');
+}
+function renderRegulatoryCompliance(compliance, report) {
+    return renderStructuredCompliance(compliance, report);
 }
 // ─── Disclaimer ─────────────────────────────────────────────────────────────
 function renderDisclaimer() {