@nebulacomponents/citable 1.18.2 → 1.20.0

package/src/reporting/executiveCroReport.js

@@ -29,6 +29,7 @@ import {
 } from '../shared/htmlEscape.js';
 import { extractHostname } from '../shared/domainUtils.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { assertEpistemicLanguage, hasVerifiedEvidenceScope } from '../shared/epistemicLanguage.js';
 
 function formatVal(v, suffix = '') {
   if (v === null || v === undefined) return 'NOT OBSERVED';
@@ -522,13 +523,20 @@ export async function buildExecutiveCroReport(root, options = {}) {
 
   const generationProvenance = {
     generated_at: generatedAt,
-    generator_version: '1.18.2',
+    generator_version: '1.19.0',
     generation_mode: resolved.generation_mode,
     source_type: resolved.source_type,
     source_identifier: resolved.source_identifier,
     source_findings_count: findings.length,
     integrity_hash: resolved.integrity_hash,
     synthetic_evidence: isSample,
+    package_verified: resolved.package_verified === true,
+    integrity_mode: resolved.integrity_mode || 'unknown',
+    legacy: resolved.legacy === true,
+    coverage_status: resolved.coverage_status || 'indeterminate',
+    determination_status: resolved.determination_status || 'indeterminate',
+    evaluated: resolved.coverage?.populations?.evaluated ?? null,
+    eligible: resolved.coverage?.populations?.eligible ?? null,
   };
 
   const report = {
@@ -542,7 +550,7 @@ export async function buildExecutiveCroReport(root, options = {}) {
     epistemological_framework: {
       observation: 'Raw empirical facts measured directly from DOM geometry, HTTP status, or analytics telemetry',
       hypothesis: 'Testable causal explanations predicting why the observed friction occurs',
-      causation: 'Statistically verified outcomes demonstrated under controlled A/B experiments with SRM checks',
+      causation: 'No current causal outcome is established; controlled A/B experiment evidence is required',
       unknowns: 'Gaps in telemetry or attribution that require further instrumentation before forming hypotheses',
     },
     pillars: {
@@ -588,7 +596,11 @@ export async function buildExecutiveCroReport(root, options = {}) {
 /**
  * Render CRO Executive Report as GitHub-flavored Markdown
  */
-export function renderCroReportMarkdown(report) {
+export function renderCroReportMarkdown(report, evidenceContext = null) {
+  const context = evidenceContext || report.generation_provenance || {};
+  const verifiedScope = hasVerifiedEvidenceScope(context);
+  const causalEvidenceVerified = verifiedScope && context.causal_evidence_verified === true;
+  const evidenceRegisterTitle = `${verifiedScope ? 'Verified Conversion Evidence Register' : 'Conversion Evidence Register (scope-limited; verified status not established)'}`;
   const p = report.pillars;
   const ds = report.decision_summary;
   const lines = [
@@ -597,7 +609,7 @@ export function renderCroReportMarkdown(report) {
     `- **Client / Property**: \`${sanitizeForMarkdown(report.client_name)}\` (\`${sanitizeForMarkdown(report.target_domain)}\`)`,
     `- **Generated At**: \`${report.generated_at}\``,
     `- **Conversion Readiness Index**: **${report.overall_conversion_readiness} / 100**`,
-    `- **Evidence Register Traceability**: ${report.evidence_register.length} verified evidence references`,
+    `- **Evidence Register Traceability**: ${report.evidence_register.length} evidence references (authority and scope recorded below)`,
     `- **Generation Mode**: \`${report.generation_provenance.generation_mode}\`${report.generation_provenance.synthetic_evidence ? ' *(Synthetic Demo Evidence)*' : ''}`,
     ``,
     `> **Scientific Epistemology & Governance Notice**: Citable enforces a strict separation between **Observable Facts**, **Predictive Hypotheses**, and **Causal Evidence**. In adherence to empirical governance, **no conversion rates, ARR lift, or metric improvements are guaranteed**.`,
@@ -613,8 +625,8 @@ export function renderCroReportMarkdown(report) {
     `*(Testable causal predictions requiring validation under controlled experimentation)*`,
     ...ds.evidence_supported_hypotheses.map((h) => `- [ ] **[HYPOTHESIS]** ${sanitizeForMarkdown(h)}`),
     ``,
-    `### 3. Causal Findings (Verified Under Controlled Experiments)`,
-    `*(Demonstrated metric shifts under A/B testing with Sample Ratio Mismatch guardrails)*`,
+    `### 3. ${causalEvidenceVerified ? 'Causal Findings (Verified Under Controlled Experiments)' : 'Causal Findings (Causal Evidence Not Established)'}`,
+    `*(${causalEvidenceVerified ? 'Demonstrated metric shifts under A/B testing with Sample Ratio Mismatch guardrails' : 'No current causal outcome is established from this report; controlled experiment evidence is required'})*`,
     ...ds.causal_findings.map((c) => `- [=] **[CAUSAL]** ${sanitizeForMarkdown(c)}`),
     ``,
     `### 4. Critical Unresolved Unknowns (Measurement Gaps)`,
@@ -694,7 +706,7 @@ export function renderCroReportMarkdown(report) {
     `- **Evidence Link**: \`${p[15].data.evidence_ref}\``,
     ...(p[15].data.top_customer_objections || []).map((o) => `- "${sanitizeForMarkdown(o)}"`),
     ``,
-    `## 15. Verified Conversion Evidence Register`,
+    `## 15. ${evidenceRegisterTitle}`,
     `| Evidence ID | Source Channel | Methodology | Confidence | Observation Date |`,
     `| :--- | :--- | :--- | :--- | :--- |`,
     ...report.evidence_register.map((e) => `| **${e.evidence_id}** | \`${escapeMarkdownTableCell(e.source)}\` | ${escapeMarkdownTableCell((e.methodology || '').slice(0, 50))}... | \`${e.confidence_level}\` | ${e.observation_date} |`),
@@ -720,16 +732,24 @@ export function renderCroReportMarkdown(report) {
     ``,
   ];
 
-  return lines.join('\n');
+  const rendered = lines.join('\n');
+  assertEpistemicLanguage(rendered, { ...context, package_verified: context.package_verified === true });
+  return rendered;
 }
 
 /**
  * Render CRO Executive Report as Standalone Enterprise HTML
  */
-export function renderCroReportHtml(report) {
+export function renderCroReportHtml(report, evidenceContext = null) {
   const p = report.pillars;
   const ds = report.decision_summary;
-  return `<!DOCTYPE html>
+  const context = evidenceContext || report.generation_provenance || {};
+  const verifiedScope = hasVerifiedEvidenceScope(context);
+  const causalEvidenceVerified = verifiedScope && context.causal_evidence_verified === true;
+  const evidenceRegisterTitle = verifiedScope
+    ? 'Verified Conversion Evidence Register'
+    : 'Conversion Evidence Register (scope-limited; verified status not established)';
+  const rendered = `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
@@ -817,13 +837,13 @@ export function renderCroReportHtml(report) {
 
     <div class="epistemic-box" style="border-left: 4px solid var(--accent-light);">
       <span class="epistemic-tag badge-causal">Causal Findings</span>
-      <p style="font-size:12px; color:var(--muted); margin: 0 0 8px 0;">Statistically verified outcomes verified under controlled A/B experiments with SRM checks.</p>
+      <p style="font-size:12px; color:var(--muted); margin: 0 0 8px 0;">${causalEvidenceVerified ? 'Statistically verified outcomes under controlled A/B experiments with SRM checks.' : 'Causal evidence is not established; controlled A/B experiment evidence is required.'}</p>
       <ul>
         ${ds.causal_findings.map((c) => `<li>${escapeHtml(c)}</li>`).join('')}
       </ul>
     </div>
 
-    <h2 class="section-title">Verified Conversion Evidence Register (${report.evidence_register.length} Observations)</h2>
+    <h2 class="section-title">${evidenceRegisterTitle} (${report.evidence_register.length} Observations)</h2>
     <table>
       <thead>
         <tr>
@@ -858,6 +878,8 @@ export function renderCroReportHtml(report) {
   </div>
 </body>
 </html>`;
+  assertEpistemicLanguage(rendered, { ...context, package_verified: context.package_verified === true });
+  return rendered;
 }
 
 /**
@@ -865,15 +887,16 @@ export function renderCroReportHtml(report) {
  */
 export async function exportExecutiveCroReport(root, options = {}) {
   const report = await buildExecutiveCroReport(root, options);
+  const evidenceContext = report.generation_provenance;
   const format = options.format || 'markdown';
   let content = '';
 
   if (format === 'html' || format === 'html-brief') {
-    content = renderCroReportHtml(report);
+    content = renderCroReportHtml(report, evidenceContext);
   } else if (format === 'json') {
     content = JSON.stringify(report, null, 2);
   } else {
-    content = renderCroReportMarkdown(report);
+    content = renderCroReportMarkdown(report, evidenceContext);
   }
 
   let outputPath = null;

package/src/reporting/executiveExport.js

@@ -3,6 +3,9 @@ import path from "node:path";
 import { readJson } from "../shared/io.js";
 import { exportExecutiveSearchReport, buildExecutiveSearchReport, renderSearchReportMarkdown, renderSearchReportHtml } from "./executiveSearchReport.js";
 import { exportExecutiveCroReport, buildExecutiveCroReport, renderCroReportMarkdown, renderCroReportHtml } from "./executiveCroReport.js";
+import { downstreamEnvelope } from '../evidence/downstream.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
+import { assertEpistemicLanguage, evidenceScopeStatement } from '../shared/epistemicLanguage.js';
 
 export {
   exportExecutiveSearchReport,
@@ -78,7 +81,7 @@ export async function exportExecutiveReport(root, runId, {
   }
 
   const runsDir = path.join(root, ".citable", "runs");
-  let targetRun = runId;
+  let targetRun = runId && fs.existsSync(path.join(root, '.citable', 'runs', runId)) ? runId : null;
 
   if (!targetRun && fs.existsSync(runsDir)) {
     const runs = fs.readdirSync(runsDir).filter((d) => !d.startsWith("."));
@@ -86,23 +89,41 @@ export async function exportExecutiveReport(root, runId, {
   }
 
   let summary = {
-    counts: { critical: 0, high: 2, medium: 4, low: 1 },
+    counts: { critical: 0, high: 0, medium: 0, low: 0 },
     posture: { retrieval: "eligible", support: "suitable", citation: "observed" },
+    coverage_status: 'indeterminate',
+    determination_status: 'indeterminate',
   };
   let findings = [];
+  let coverage = null;
+  let packageVerified = false;
 
   if (targetRun) {
-    const sumPath = path.join(runsDir, targetRun, "summary.json");
-    if (fs.existsSync(sumPath)) {
-      try { summary = readJson(sumPath); } catch {}
-    }
-    const findPath = path.join(runsDir, targetRun, "findings.json");
-    if (fs.existsSync(findPath)) {
-      try { findings = readJson(findPath); } catch {}
-    }
+    const loaded = loadVerifiedRun(path.join(runsDir, targetRun), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+    summary = loaded.summary || summary;
+    findings = loaded.findings;
+    coverage = loaded.coverage;
+    packageVerified = loaded.verified === true && loaded.integrity_mode === 'sealed';
+    summary.coverage_status = loaded.coverage_status;
+    summary.determination_status = loaded.determination_status;
   }
 
+  const evidence = downstreamEnvelope(coverage);
+  summary.coverage_status = evidence.coverage_status;
+  summary.determination_status = evidence.determination_status;
+  summary.coverage = {
+    ...evidence.evidence_scope,
+    limitations: evidence.limitations,
+  };
+
   let content = "";
+  const evidenceNotice = `Evidence determination: ${summary.determination_status} (coverage: ${summary.coverage_status}; evaluated ${summary.coverage.evaluated ?? 0} of ${summary.coverage.eligible ?? 'unknown'} eligible). ${summary.coverage.limitations.join('; ') || evidenceScopeStatement({
+    coverage_status: summary.coverage_status,
+    determination_status: summary.determination_status,
+    evaluated: summary.coverage.evaluated,
+    eligible: summary.coverage.eligible,
+    package_verified: packageVerified,
+  })}`;
 
   if (format === "html-brief") {
     content = `<!DOCTYPE html>
@@ -136,6 +157,7 @@ export async function exportExecutiveReport(root, runId, {
   <div class="disclosure">
     <strong>Regulatory & Governance Notice:</strong> Citable measures observable retrieval suitability, source extraction fidelity, and external AI citation outcomes. Citable does not guarantee search crawling, indexing, ranking, citation, recommendation, or conversion.
   </div>
+  <p class="disclosure"><strong>${evidenceNotice}</strong></p>
 
   <div class="kpi-grid">
     <div class="kpi-card"><div>Critical Risks</div><div class="kpi-val ${(summary.counts?.critical || 0) > 0 ? "crit" : "healthy"}">${summary.counts?.critical || 0}</div></div>
@@ -150,10 +172,7 @@ export async function exportExecutiveReport(root, runId, {
       <tr><th>Detector</th><th>Severity</th><th>Summary</th><th>Required Remediation</th></tr>
     </thead>
     <tbody>
-      ${(findings.length > 0 ? findings : [
-        { detector_id: "CRO-015", severity: "low", summary: "Mobile touch target below 44px on primary CTA", remediation: "Increase button min-height to 48px" },
-        { detector_id: "GEO-008", severity: "high", summary: "Attribution distortion in AI search citation", remediation: "Corroborate claims directly on landing page" },
-      ]).map((f) => `
+      ${(findings.length > 0 ? findings : [{ detector_id: "—", severity: "informational", summary: evidenceNotice, remediation: "Collect sufficient evidence before drawing a site-wide determination" }]).map((f) => `
         <tr>
           <td><code>${f.detector_id}</code></td>
           <td><span class="badge badge-${f.severity}">${f.severity.toUpperCase()}</span></td>
@@ -174,11 +193,13 @@ export async function exportExecutiveReport(root, runId, {
 - **High Severity Findings**: ${summary.counts?.high || 0}
 - **Medium Severity Findings**: ${summary.counts?.medium || 0}
 
+> **${evidenceNotice}** Findings remain limited to the evaluated evidence scope.
+
 > Citable does not guarantee crawling, indexing, ranking, citation, or conversion.
 
 <!-- slide -->
 ## Prioritized Action Items
-${findings.slice(0, 5).map((f) => `- **[${f.detector_id}]** (${f.severity}): ${f.summary}`).join("\n") || "- No blocking findings detected."}
+${findings.slice(0, 5).map((f) => `- **[${f.detector_id}]** (${f.severity}): ${f.summary}`).join("\n") || `- No determination established from the available evidence (${summary.determination_status || 'indeterminate'}).`}
 `;
   } else if (format === "slides") {
     const fsa = findings.reduce((acc, f) => {
@@ -263,7 +284,7 @@ ${findings.slice(0, 5).map((f) => `- **[${f.detector_id}]** (${f.severity}): ${f
     <h2>Prioritized Remediations</h2>
     <p>Every finding maps directly to a production-ready, accessible Nebula Component:</p>
     <div style="background:#1e293b; border-radius:0.75rem; padding:1.5rem; border:1px solid #334155;">
-      ${findings.slice(0, 4).map((f) => `<div style="padding:0.5rem 0; border-bottom:1px solid #334155; font-size:1.1rem;"><strong>[${f.detector_id || "CRO"}]</strong>: ${f.summary || "Conversion action friction"}</div>`).join("") || "<p>All conversion pathways verified clean.</p>"}
+      ${findings.slice(0, 4).map((f) => `<div style="padding:0.5rem 0; border-bottom:1px solid #334155; font-size:1.1rem;"><strong>[${f.detector_id || "CRO"}]</strong>: ${f.summary || "Conversion action friction"}</div>`).join("") || `<p>No determination established from the available evidence (${summary.determination_status || 'indeterminate'}).</p>`}
     </div>
     <div style="margin-top:1.5rem; font-family:monospace; background:#0f172a; padding:1rem; border-radius:0.5rem; border:1px solid #334155; color:#38bdf8;">
       $ npx @nebulacomponents/citable remediate --finding CRO-007 --write
@@ -300,6 +321,14 @@ ${findings.slice(0, 5).map((f) => `- **[${f.detector_id}]** (${f.severity}): ${f
     fs.writeFileSync(path.resolve(root, output), content, "utf8");
   }
 
+  const languageContext = {
+    coverage_status: summary.coverage_status,
+    determination_status: summary.determination_status,
+    evaluated: summary.coverage.evaluated,
+    eligible: summary.coverage.eligible,
+    package_verified: packageVerified,
+  };
+  assertEpistemicLanguage(content, languageContext);
   return {
     format,
     client_name: clientName,

package/src/reporting/executiveSearchReport.js

@@ -31,6 +31,7 @@ import {
 } from '../shared/htmlEscape.js';
 import { extractHostname } from '../shared/domainUtils.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { assertEpistemicLanguage, hasVerifiedEvidenceScope } from '../shared/epistemicLanguage.js';
 
 function formatVal(v, suffix = '') {
   if (v === null || v === undefined) return 'NOT OBSERVED';
@@ -613,13 +614,20 @@ export async function buildExecutiveSearchReport(root, options = {}) {
 
   const generationProvenance = {
     generated_at: generatedAt,
-    generator_version: '1.18.2',
+    generator_version: '1.19.0',
     generation_mode: resolved.generation_mode,
     source_type: resolved.source_type,
     source_identifier: resolved.source_identifier,
     source_findings_count: findings.length,
     integrity_hash: resolved.integrity_hash,
     synthetic_evidence: isSample,
+    package_verified: resolved.package_verified === true,
+    integrity_mode: resolved.integrity_mode || 'unknown',
+    legacy: resolved.legacy === true,
+    coverage_status: resolved.coverage_status || 'indeterminate',
+    determination_status: resolved.determination_status || 'indeterminate',
+    evaluated: resolved.coverage?.populations?.evaluated ?? null,
+    eligible: resolved.coverage?.populations?.eligible ?? null,
   };
 
   const report = {
@@ -667,7 +675,15 @@ export async function buildExecutiveSearchReport(root, options = {}) {
 /**
  * Render Search Executive Report as GitHub-flavored Markdown
  */
-export function renderSearchReportMarkdown(report) {
+export function renderSearchReportMarkdown(report, evidenceContext = null) {
+  const context = evidenceContext || report.generation_provenance || {};
+  const verifiedScope = hasVerifiedEvidenceScope(context);
+  const scopedValue = (value) => {
+    if (!verifiedScope && typeof value === 'string' && /\b(?:verified|clean|resolved|optimal|passed)\b|(?:verified_source|clean_profile)/i.test(value)) return 'NOT ESTABLISHED';
+    return value;
+  };
+  const scopedFormat = (value, suffix = '') => scopedValue(formatVal(value, suffix));
+  const evidenceRegisterTitle = `${verifiedScope ? 'Verified Evidence Register' : 'Evidence Register (scope-limited; verified status not established)'} (Traceability Engine)`;
   const p = report.pillars;
   const lines = [
     `# ${sanitizeForMarkdown(report.report_title)}`,
@@ -675,7 +691,7 @@ export function renderSearchReportMarkdown(report) {
     `- **Client / Property**: \`${sanitizeForMarkdown(report.client_name)}\` (\`${sanitizeForMarkdown(report.target_domain)}\`)`,
     `- **Generated At**: \`${report.generated_at}\``,
     `- **Overall Search & AEO Readiness Score**: **${report.overall_readiness_score} / 100**`,
-    `- **Evidence Register Traceability**: ${report.evidence_register.length} verified evidence references`,
+    `- **Evidence Register Traceability**: ${report.evidence_register.length} evidence references (authority and scope recorded below)`,
     `- **Generation Mode**: \`${report.generation_provenance.generation_mode}\`${report.generation_provenance.synthetic_evidence ? ' *(Synthetic Demo Evidence)*' : ''}`,
     ``,
     `> **Operating Premise & Governance Notice**: This executive report presents observable technical search infrastructure, content extraction posture, and controlled citation behavior. In adherence to Citable governance principles, **no search ranking, AI citation, or conversion outcomes are guaranteed**.`,
@@ -684,7 +700,7 @@ export function renderSearchReportMarkdown(report) {
     `## Executive Decision Summary (Traceable Conclusions)`,
     ``,
     `### 1. Confirmed Findings (Deterministic Observations)`,
-    ...report.decision_summary.confirmed_findings.map((f) => `- [x] **[VERIFIED]** ${sanitizeForMarkdown(f)}`),
+    ...report.decision_summary.confirmed_findings.map((f) => `- [x] **[OBSERVED]** ${sanitizeForMarkdown(f)}`),
     ``,
     `### 2. Inferred Opportunities (Modeled Projections)`,
     ...report.decision_summary.inferred_opportunities.map((o) => `- [ ] **[OPPORTUNITY]** ${sanitizeForMarkdown(o)}`),
@@ -703,13 +719,13 @@ export function renderSearchReportMarkdown(report) {
     `- **Evidence Link**: \`${p[1].data.evidence_ref}\``,
     `- **Google Organic Indexing**: ${formatVal(p[1].data.google_organic?.indexed_status).toUpperCase()}`,
     `- **Google AI Overviews**: ${formatVal(p[1].data.google_ai_overviews?.inclusion_rate_pct, '%')} inclusion rate (Risk: \`${formatVal(p[1].data.google_ai_overviews?.risk_exposure)}\`)`,
-    `- **AI Engine Presence**: Perplexity (\`${formatVal(p[1].data.ai_answer_engines?.perplexity)}\`), ChatGPT (\`${formatVal(p[1].data.ai_answer_engines?.chatgpt_search)}\`), Copilot (\`${formatVal(p[1].data.ai_answer_engines?.copilot)}\`)`,
+    `- **AI Engine Presence**: Perplexity (\`${scopedFormat(p[1].data.ai_answer_engines?.perplexity)}\`), ChatGPT (\`${scopedFormat(p[1].data.ai_answer_engines?.chatgpt_search)}\`), Copilot (\`${scopedFormat(p[1].data.ai_answer_engines?.copilot)}\`)`,
     ``,
     `## 2. Technical Search Infrastructure & Core Web Vitals`,
     `- **Evidence Link**: \`${p[2].data.evidence_ref}\``,
-    `- **Crawlability & Canonicals**: ${formatVal(p[2].data.canonical_integrity).toUpperCase()}`,
-    `- **LCP Readiness**: ${formatVal(p[2].data.core_web_vitals?.lcp_status).toUpperCase()} (${formatVal(p[2].data.core_web_vitals?.render_blocking_scripts)} render-blocking assets)`,
-    `- **CLS Readiness**: ${formatVal(p[2].data.core_web_vitals?.cls_status).toUpperCase()} (${formatVal(p[2].data.core_web_vitals?.unsized_images)} unsized images)`,
+    `- **Crawlability & Canonicals**: ${scopedFormat(p[2].data.canonical_integrity).toUpperCase()}`,
+    `- **LCP Readiness**: ${scopedFormat(p[2].data.core_web_vitals?.lcp_status).toUpperCase()} (${formatVal(p[2].data.core_web_vitals?.render_blocking_scripts)} render-blocking assets)`,
+    `- **CLS Readiness**: ${scopedFormat(p[2].data.core_web_vitals?.cls_status).toUpperCase()} (${formatVal(p[2].data.core_web_vitals?.unsized_images)} unsized images)`,
     ``,
     `## 3. Organic Performance & Search Intent Analysis`,
     `- **Evidence Link**: \`${p[3].data.evidence_ref}\``,
@@ -724,7 +740,7 @@ export function renderSearchReportMarkdown(report) {
     ``,
     `## 5. AEO Readiness Assessment (Answer Engine Optimization)`,
     `- **Evidence Link**: \`${p[5].data.evidence_ref}\``,
-    `- **Overall AEO Readiness Score**: **${formatVal(p[5].data.readiness_score)} / 100** (${formatVal(p[5].data.status).toUpperCase()})`,
+    `- **Overall AEO Readiness Score**: **${formatVal(p[5].data.readiness_score)} / 100** (${scopedFormat(p[5].data.status).toUpperCase()})`,
     `- **Direct Answer Density**: ${formatVal(p[5].data.direct_extract_density)}`,
     ``,
     `## 6. GEO Assessment (Generative Engine Optimization)`,
@@ -743,7 +759,7 @@ export function renderSearchReportMarkdown(report) {
     `## 8. Entity & Knowledge Graph Integrity`,
     `- **Evidence Link**: \`${p[8].data.evidence_ref}\``,
     `- **Organization Node Resolved**: ${p[8].data.organization_node_resolved ? 'YES' : 'NO'}`,
-    `- **External Corroboration**: ${formatVal(p[8].data.wikidata_corroboration).toUpperCase()}`,
+    `- **External Corroboration**: ${scopedFormat(p[8].data.wikidata_corroboration).toUpperCase()}`,
     ``,
     `## 9. Structured-Data & Schema Architecture`,
     `- **Evidence Link**: \`${p[9].data.evidence_ref}\``,
@@ -753,12 +769,12 @@ export function renderSearchReportMarkdown(report) {
     `## 10. Competitive Search Intelligence & Share of Voice`,
     `- **Evidence Link**: \`${p[10].data.evidence_ref}\``,
     `- **1st-Party Citation Share**: **${formatVal(p[10].data.first_party_citation_share_pct, '%')}** vs Competitors (${formatVal(p[10].data.top_competitor_share_pct, '%')})`,
-    `- **Primary Gap**: ${formatVal(p[10].data.primary_authority_gap)}`,
+    `- **Primary Gap**: ${scopedFormat(p[10].data.primary_authority_gap)}`,
     ``,
     `## 11. Backlink & Off-Page Authority Profile`,
     `- **Evidence Link**: \`${p[11].data.evidence_ref}\``,
     `- **Referring Domains**: ${formatVal(p[11].data.referring_domains)} (Authority Score: ${formatVal(p[11].data.authority_score)}/100)`,
-    `- **Toxic Domains**: ${formatVal(p[11].data.toxic_domain_count)} flagged (\`${formatVal(p[11].data.disavow_recommendation)}\`)`,
+    `- **Toxic Domains**: ${formatVal(p[11].data.toxic_domain_count)} flagged (\`${scopedFormat(p[11].data.disavow_recommendation)}\`)`,
     ``,
     `## 12. Search Demand & Addressable Market Opportunity`,
   ];
@@ -782,11 +798,11 @@ export function renderSearchReportMarkdown(report) {
     `- **Assisted Conversions Share**: ${formatVal(p[13].data.assisted_conversions_share_pct, '%')}`,
     ``,
     `## 14. Measurement Integrity & Analytics Instrumentation`,
-    `- **GA4 & GSC**: ${formatVal(p[14].data.ga4_instrumentation).toUpperCase()} / ${formatVal(p[14].data.gsc_property_binding).toUpperCase()}`,
+    `- **GA4 & GSC**: ${formatVal(scopedValue(p[14].data.ga4_instrumentation)).toUpperCase()} / ${formatVal(scopedValue(p[14].data.gsc_property_binding)).toUpperCase()}`,
     `- **Consent Mode Data Loss**: ${formatVal(p[14].data.consent_mode_v2_loss_pct, '%')}`,
     `- **Limitations**: ${(p[14].data.known_limitations || []).map((l) => sanitizeForMarkdown(l)).join('; ')}`,
     ``,
-    `## 15. Verified Evidence Register (Traceability Engine)`,
+    `## 15. ${evidenceRegisterTitle}`,
     `| Evidence ID | Source | Methodology | Confidence | Observation Date |`,
     `| :--- | :--- | :--- | :--- | :--- |`,
     ...report.evidence_register.map((e) => `| **${e.evidence_id}** | \`${escapeMarkdownTableCell(e.source)}\` | ${escapeMarkdownTableCell((e.methodology || '').slice(0, 50))}... | \`${e.confidence_level}\` | ${e.observation_date} |`),
@@ -806,15 +822,30 @@ export function renderSearchReportMarkdown(report) {
     ``
   );
 
-  return lines.join('\n');
+  const rendered = lines.join('\n');
+  assertEpistemicLanguage(rendered, { ...context, package_verified: context.package_verified === true });
+  return rendered;
 }
 
 /**
  * Render Search Executive Report as Standalone Enterprise HTML
  */
-export function renderSearchReportHtml(report) {
+export function renderSearchReportHtml(report, evidenceContext = null) {
   const p = report.pillars;
-  return `<!DOCTYPE html>
+  const context = evidenceContext || report.generation_provenance || {};
+  const verifiedScope = hasVerifiedEvidenceScope(context);
+  const evidenceRegisterTitle = verifiedScope
+    ? 'Verified Evidence Register'
+    : 'Evidence Register (scope-limited; verified status not established)';
+  const readinessLabel = verifiedScope ? (report.overall_readiness_score >= 70 ? 'Strong observed posture' : 'Needs optimization') : 'Not established';
+  const cwvLabel = verifiedScope && p[2].data.core_web_vitals?.render_blocking_scripts === 0 ? 'No flagged blockers' : 'Not established';
+  const scopedFormat = (value, suffix = '') => {
+    const rendered = formatVal(value, suffix);
+    return !verifiedScope && typeof rendered === 'string' && /\b(?:verified|clean|resolved|optimal|passed)\b|(?:verified_source|clean_profile)/i.test(rendered)
+      ? 'NOT ESTABLISHED'
+      : rendered;
+  };
+  const rendered = `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
@@ -861,12 +892,12 @@ export function renderSearchReportHtml(report) {
       <div class="card">
         <div style="font-size:12px; color:var(--muted); text-transform:uppercase;">Composite Search Readiness</div>
         <div class="card-num">${report.overall_readiness_score} / 100</div>
-        <span class="badge ${report.overall_readiness_score >= 70 ? 'badge-success' : 'badge-warning'}">${report.overall_readiness_score >= 70 ? 'Optimal' : 'Needs Optimization'}</span>
+        <span class="badge ${verifiedScope && report.overall_readiness_score >= 70 ? 'badge-success' : 'badge-warning'}">${readinessLabel}</span>
       </div>
       <div class="card">
         <div style="font-size:12px; color:var(--muted); text-transform:uppercase;">AEO Direct Extraction</div>
         <div class="card-num">${formatVal(p[5].data.readiness_score)}</div>
-        <span class="badge badge-success">${formatVal(p[5].data.status).toUpperCase()}</span>
+        <span class="badge badge-success">${scopedFormat(p[5].data.status).toUpperCase()}</span>
       </div>
       <div class="card">
         <div style="font-size:12px; color:var(--muted); text-transform:uppercase;">E-E-A-T Quality Score</div>
@@ -876,11 +907,11 @@ export function renderSearchReportHtml(report) {
       <div class="card">
         <div style="font-size:12px; color:var(--muted); text-transform:uppercase;">Core Web Vitals Blockers</div>
         <div class="card-num">${formatVal(p[2].data.core_web_vitals?.render_blocking_scripts)}</div>
-        <span class="badge ${p[2].data.core_web_vitals?.render_blocking_scripts === 0 ? 'badge-success' : 'badge-danger'}">${p[2].data.core_web_vitals?.render_blocking_scripts === 0 ? 'Clean' : 'Action Required'}</span>
+        <span class="badge ${verifiedScope && p[2].data.core_web_vitals?.render_blocking_scripts === 0 ? 'badge-success' : 'badge-danger'}">${cwvLabel}</span>
       </div>
     </div>
 
-    <h2 class="section-title">Verified Evidence Register (${report.evidence_register.length} Observations)</h2>
+    <h2 class="section-title">${evidenceRegisterTitle} (${report.evidence_register.length} Observations)</h2>
     <table>
       <thead>
         <tr>
@@ -915,6 +946,8 @@ export function renderSearchReportHtml(report) {
   </div>
 </body>
 </html>`;
+  assertEpistemicLanguage(rendered, { ...context, package_verified: context.package_verified === true });
+  return rendered;
 }
 
 /**
@@ -922,15 +955,16 @@ export function renderSearchReportHtml(report) {
  */
 export async function exportExecutiveSearchReport(root, options = {}) {
   const report = await buildExecutiveSearchReport(root, options);
+  const evidenceContext = report.generation_provenance;
   const format = options.format || 'markdown';
   let content = '';
 
   if (format === 'html' || format === 'html-brief') {
-    content = renderSearchReportHtml(report);
+    content = renderSearchReportHtml(report, evidenceContext);
   } else if (format === 'json') {
     content = JSON.stringify(report, null, 2);
   } else {
-    content = renderSearchReportMarkdown(report);
+    content = renderSearchReportMarkdown(report, evidenceContext);
   }
 
   let outputPath = null;

package/src/reporting/report.js

@@ -1,3 +1,5 @@
+import { assertEpistemicLanguage, evidenceScopeStatement } from '../shared/epistemicLanguage.js';
+
 const SEV_ORDER = { critical: 0, high: 1, medium: 2, low: 3, informational: 4, experimental: 5 };
 
 const RETRIEVAL_NAMESPACES = new Set(['TECH', 'CRAWL', 'LINK', 'HREFLANG']);
@@ -39,7 +41,7 @@ function citationPosture(promptResults, targetOrigin) {
   };
 }
 
-export function summarize(findings, { detectorsRun = [], detectorsSkipped = [], promptResults = [], targetOrigin = null } = {}) {
+export function summarize(findings, { detectorsRun = [], detectorsSkipped = [], promptResults = [], targetOrigin = null, coverage = null } = {}) {
   const bySeverity = {};
   const byNamespace = {};
   const byDiscipline = { seo: 0, aeo: 0, geo: 0 };
@@ -51,6 +53,18 @@ export function summarize(findings, { detectorsRun = [], detectorsSkipped = [],
     for (const d of f.discipline) byDiscipline[d] = (byDiscipline[d] || 0) + 1;
     if (f.classification.deterministic) deterministic++;
   }
+  const coverageIncomplete = coverage && coverage.coverage_status !== 'complete';
+  const posture = {
+    retrieval_eligibility: readinessPosture(findings, detectorsRun, detectorsSkipped, RETRIEVAL_NAMESPACES),
+    source_extraction_and_support: readinessPosture(findings, detectorsRun, detectorsSkipped, SOURCE_NAMESPACES),
+    observed_citation_behavior: citationPosture(promptResults, targetOrigin),
+  };
+  if (coverageIncomplete) {
+    for (const key of ['retrieval_eligibility', 'source_extraction_and_support']) {
+      posture[key].result = 'qualified';
+      posture[key].coverage_status = coverage.coverage_status;
+    }
+  }
   return {
     total: findings.length,
     deterministic_observations: deterministic,
@@ -58,15 +72,22 @@ export function summarize(findings, { detectorsRun = [], detectorsSkipped = [],
     by_severity: bySeverity,
     by_namespace: byNamespace,
     by_discipline: byDiscipline,
-    posture: {
-      retrieval_eligibility: readinessPosture(findings, detectorsRun, detectorsSkipped, RETRIEVAL_NAMESPACES),
-      source_extraction_and_support: readinessPosture(findings, detectorsRun, detectorsSkipped, SOURCE_NAMESPACES),
-      observed_citation_behavior: citationPosture(promptResults, targetOrigin),
-    },
+    coverage: coverage ? {
+      status: coverage.coverage_status,
+      populations: coverage.populations,
+      stop_reason: coverage.stop_reason,
+    } : null,
+    posture,
   };
 }
 
-export function renderMarkdownReport({ findings, manifest, summary, detectorsSkipped = [] }) {
+export function renderMarkdownReport({ findings, manifest, summary, detectorsSkipped = [], coverage = null, verifiedRun = null }) {
+  // Only the verified loader can establish package integrity. Manifest flags
+  // are part of the package input and therefore cannot establish their own
+  // trustworthiness when this renderer is called directly.
+  const packageVerified = verifiedRun?.verified === true
+    && verifiedRun?.integrity_mode === 'sealed'
+    && typeof verifiedRun?.verification_version === 'string';
   const lines = [];
   lines.push(`# Citable audit report`);
   lines.push('');
@@ -85,10 +106,18 @@ export function renderMarkdownReport({ findings, manifest, summary, detectorsSki
   lines.push(`| Total findings | ${summary.total} |`);
   lines.push(`| Deterministic observations | ${summary.deterministic_observations} |`);
   lines.push(`| Heuristic / semantic findings | ${summary.semantic_or_heuristic} |`);
+  if (coverage) {
+    lines.push(`| Coverage status | ${coverage.coverage_status} |`);
+    lines.push(`| Evaluated resources | ${coverage.populations.evaluated} of ${coverage.populations.discovered - coverage.populations.excluded} eligible |`);
+  }
   for (const [sev, n] of Object.entries(summary.by_severity).sort((a, b) => SEV_ORDER[a[0]] - SEV_ORDER[b[0]])) {
     lines.push(`| ${sev} | ${n} |`);
   }
   lines.push('');
+  if (coverage && coverage.coverage_status !== 'complete') {
+    lines.push(`> Coverage status: **${coverage.coverage_status}**. This report describes the observed corpus and does not establish a complete site-wide determination.`);
+    lines.push('');
+  }
   lines.push('## Separate eligibility and observation states');
   lines.push('');
   lines.push('| Dimension | Result | Evidence |');
@@ -132,8 +161,26 @@ export function renderMarkdownReport({ findings, manifest, summary, detectorsSki
     lines.push('');
   }
   if (findings.length === 0) {
-    lines.push(`No findings from the executed detectors. Absence of findings is not proof of eligibility — see skipped and incomplete checks above.`);
+    const population = coverage?.populations?.evaluated ?? 0;
+    lines.push(population > 0
+      ? `No findings were produced for the ${population} successfully evaluated resource(s). Absence of findings is not proof of eligibility — see skipped and incomplete checks above.`
+      : evidenceScopeStatement({
+        coverage_status: coverage?.coverage_status || 'indeterminate',
+        determination_status: summary?.posture?.source_extraction_and_support?.result === 'pass' ? 'supported' : 'indeterminate',
+        evaluated: 0,
+        eligible: coverage?.populations?.eligible ?? 0,
+        legacy: !coverage,
+      }));
     lines.push('');
   }
-  return lines.join('\n');
+  const rendered = lines.join('\n');
+  assertEpistemicLanguage(rendered, {
+    coverage_status: coverage?.coverage_status || 'indeterminate',
+    determination_status: coverage?.coverage_status === 'complete' ? 'supported' : 'indeterminate',
+    evaluated: coverage?.populations?.evaluated ?? 0,
+    eligible: coverage?.populations?.eligible ?? 0,
+    package_verified: packageVerified,
+    legacy: verifiedRun?.legacy === true || !coverage,
+  });
+  return rendered;
 }