@nebulacomponents/citable 1.18.2 → 1.20.0

package/src/commands/connect.js

@@ -79,16 +79,37 @@ export async function syncConnection(root, { connectionId, startDate, endDate, a
     }
     throw error;
   }
+  // Connector collection may preserve a partial result even when the provider
+  // reports an authorization/quota state. Keep the result available to direct
+  // connector callers, while retaining the command's legacy state transition.
+  if (result.connectorError?.connectorState) {
+    const error = result.connectorError;
+    const failed = { ...loaded.registries.connections, entries: loaded.registries.connections.entries.map((item) => item.connection_id === connectionId ? { ...item, state: error.connectorState, limitations: [...(result.collection?.errors || []), 'Connector synchronization did not complete; inspect collection errors.'] } : item) };
+    saveRegistry(root, 'connections', failed);
+    throw error;
+  }
+  const collection = result.collection || {
+    schema_version: 1,
+    items: result.rows,
+    pagination_state: { pages_requested: 1, pages_retrieved: 1 },
+    provider_reported_total: null,
+    retrieved_total: result.rows.length,
+    coverage_status: 'indeterminate',
+    continuation_state: null,
+    limitations: ['Connector did not provide a collection contract.'],
+    errors: [],
+  };
+  const collectionLimitations = [...collection.limitations, ...collection.errors];
   const observations = result.rows.map((row) => envelope('metric', {
     metric_id: row.metric.metric_id, provider: connector.provider, external_name: row.metric.external_name,
     value: Number(row.value), unit: row.metric.unit === 'custom' ? row.metric.custom_unit : row.metric.unit,
     aggregation: row.metric.aggregation, observed_at: row.observed_at, period_start: row.observed_at,
     period_end: row.observed_at, dimensions: row.dimensions,
-  }, { method: 'live_api', source: connector.provider, limitations: [...row.metric.limitations, ...result.limitations] }));
+  }, { method: 'live_api', source: connector.provider, limitations: [...row.metric.limitations, ...collectionLimitations] }));
   const run = observationRun(root, 'connect sync', loaded.connection.property_id, observations);
-  const updated = { ...loaded.registries.connections, entries: loaded.registries.connections.entries.map((item) => item.connection_id === connectionId ? { ...item, state: 'synchronized', last_synchronized_at: new Date().toISOString(), cursor: result.cursor, limitations: result.limitations } : item) };
+  const updated = { ...loaded.registries.connections, entries: loaded.registries.connections.entries.map((item) => item.connection_id === connectionId ? { ...item, state: ['truncated', 'indeterminate'].includes(collection.coverage_status) ? 'partial' : 'synchronized', last_synchronized_at: new Date().toISOString(), cursor: result.cursor, limitations: collectionLimitations } : item) };
   saveRegistry(root, 'connections', updated);
-  return { ...run, connection_id: connectionId, provider: connector.provider };
+  return { ...run, connection_id: connectionId, provider: connector.provider, collection };
 }
 
 export async function readCmsContent(root, { connectionId, targetId, accessToken, env, fetchImpl } = {}) {
@@ -119,4 +140,3 @@ export async function applyCmsRemediation(root, { connectionId, input, write = f
 
 export { submitIndexNow, verifyHostKey, buildIndexNowPayload, normalizeHost, parseUrlsInput } from '../connectors/indexnow.js';
 export { collectMcpEvidence } from '../connectors/mcp/pilot.js';
-

package/src/commands/context.js

@@ -4,8 +4,44 @@ import { readYaml, readJson, sha256, parseRefDate } from '../shared/io.js';
 import { loadRegistries } from '../registries/index.js';
 import { buildSiteFromDir, buildSiteFromUrl } from '../extractor/site.js';
 
+const AUDIT_BUDGET_DEFAULTS = Object.freeze({ maxPages: 500, timeBudgetSeconds: 1800 });
+
+function validateBudget(value, name, maximum) {
+  if (!Number.isInteger(value) || value < 1 || value > maximum) {
+    throw new Error(`${name} must be an integer from 1 to ${maximum}; received ${String(value)}`);
+  }
+  return value;
+}
+
+/** Resolve bounded network collection budgets: command options > config > safe defaults. */
+export function resolveAuditBudgets(config = {}, options = {}) {
+  const configured = config.audit ?? {};
+  const maxPagesFromOptions = options.maxPages !== undefined;
+  const timeBudgetFromOptions = options.timeBudgetSeconds !== undefined;
+  const maxPages = maxPagesFromOptions
+    ? options.maxPages
+    : configured.max_pages !== undefined ? configured.max_pages : AUDIT_BUDGET_DEFAULTS.maxPages;
+  const timeBudgetSeconds = timeBudgetFromOptions
+    ? options.timeBudgetSeconds
+    : configured.time_budget_seconds !== undefined
+      ? configured.time_budget_seconds
+      : AUDIT_BUDGET_DEFAULTS.timeBudgetSeconds;
+
+  return {
+    maxPages: validateBudget(maxPages, maxPagesFromOptions ? '--max-pages' : 'audit.max_pages', 10_000),
+    timeBudgetSeconds: validateBudget(
+      timeBudgetSeconds,
+      timeBudgetFromOptions ? '--time-budget-seconds' : 'audit.time_budget_seconds',
+      86_400,
+    ),
+  };
+}
+
 /** Assemble the shared execution context used by audit-family commands. */
-export async function buildContext(root, { target, baseUrl, refDate, viewport = null } = {}) {
+export async function buildContext(root, {
+  target, baseUrl, refDate, viewport = null,
+  maxPages, timeBudgetSeconds, fetcher, concurrency = 1,
+} = {}) {
   const warnings = [];
   const configFile = path.join(root, '.citable', 'config.yaml');
   const config = fs.existsSync(configFile) ? readYaml(configFile) : { version: 1 };
@@ -13,10 +49,12 @@ export async function buildContext(root, { target, baseUrl, refDate, viewport =
   warnings.push(...problems);
 
   let site = null;
+  let auditBudgets = null;
   const resolvedBase = baseUrl ?? config.site?.base_url ?? 'https://example.test';
   if (target) {
     if (/^https?:\/\//.test(target)) {
-      site = await buildSiteFromUrl(target);
+      auditBudgets = resolveAuditBudgets(config, { maxPages, timeBudgetSeconds });
+      site = await buildSiteFromUrl(target, { ...auditBudgets, fetcher, concurrency });
     } else if (fs.existsSync(target)) {
       site = buildSiteFromDir(target, { baseUrl: resolvedBase });
     } else {
@@ -70,6 +108,7 @@ export async function buildContext(root, { target, baseUrl, refDate, viewport =
     promptResults: promptResults.length ? promptResults : null,
     observations: observations.length ? observations : null,
     snapshots,
+    auditBudgets,
     refDate: parseRefDate(refDate),
     viewport,
     hashPage: (p) => sha256(p.text),

package/src/commands/croSuite.js

@@ -9,6 +9,7 @@ import { analyzeBehavioralTelemetry } from '../analysis/behavioral.js';
 import { generateExperimentBacklog, formatBacklogMarkdown } from './croBacklog.js';
 import { buildIceMatrix, formatIceMatrixOutput } from '../analysis/iceMatrix.js';
 import { buildCroRoadmap, formatCroRoadmapMarkdown } from '../analysis/croRoadmap.js';
+import { downstreamEnvelope, completeLocalCoverage } from '../evidence/downstream.js';
 
 /**
  * Full End-to-End CRO Intelligence Suite Audit
@@ -22,6 +23,8 @@ export async function auditCroSuite(root, { target, baseUrl, refDate, input, fun
   const { findings } = runDetectors(croDetectors, ctx);
 
   const pages = indexTargets(ctx);
+  const coverage = ctx.coverage || (pages.length > 0 ? completeLocalCoverage(pages, ctx.site.baseUrl) : null);
+  const evidence = downstreamEnvelope(coverage);
 
   // 2. Above-the-fold clarity, trust, cognitive load, offer architecture per page
   const auditedPages = pages.map((page) => auditPageCro(page, ctx));
@@ -33,21 +36,29 @@ export async function auditCroSuite(root, { target, baseUrl, refDate, input, fun
   });
   const targetGroup = commercialPages.length > 0 ? commercialPages : auditedPages;
 
-  const avgAtfClarity = targetGroup.length > 0
+  const avgAtfClarity = targetGroup.length > 0 && evidence.determination_status !== 'indeterminate'
     ? Math.round(targetGroup.reduce((acc, p) => acc + p.atf_clarity.score, 0) / targetGroup.length)
-    : 0;
+    : null;
 
-  const avgTrustScore = targetGroup.length > 0
+  const avgTrustScore = targetGroup.length > 0 && evidence.determination_status !== 'indeterminate'
     ? Math.round(targetGroup.reduce((acc, p) => acc + p.trust_and_credibility.score, 0) / targetGroup.length)
-    : 0;
+    : null;
 
-  const avgConversionReadiness = targetGroup.length > 0
+  const avgConversionReadiness = targetGroup.length > 0 && evidence.determination_status !== 'indeterminate'
     ? Math.round(targetGroup.reduce((acc, p) => acc + p.conversion_readiness_score, 0) / targetGroup.length)
-    : 0;
+    : null;
 
   // 3. End-to-end Funnel and Conversion-Path Analysis
   const declaredFunnel = (ctx.registries?.funnels?.entries || []).find((f) => funnelId ? f.funnel_id === funnelId : true) || null;
   const funnelAnalysis = analyzeConversionFunnel(ctx.site.pages, declaredFunnel);
+  const qualify = (value) => evidence.determination_status === 'supported' ? value : null;
+  const qualifiedFunnel = {
+    ...funnelAnalysis,
+    funnel_health_score: qualify(funnelAnalysis.funnel_health_score),
+    determination_status: evidence.determination_status,
+    coverage_status: evidence.coverage_status,
+    limitations: evidence.limitations,
+  };
 
   // 4. Behavioral Evidence Analysis (if telemetry file provided)
   let behavioralAnalysis = null;
@@ -65,9 +76,26 @@ export async function auditCroSuite(root, { target, baseUrl, refDate, input, fun
 
   // 5. Experiment Backlog with Falsifiable Hypotheses
   const experimentBacklog = generateExperimentBacklog(findings);
+  const qualifiedExperimentBacklog = {
+    ...experimentBacklog,
+    total_experiments: qualify(experimentBacklog.total_experiments),
+    determination_status: evidence.determination_status,
+    coverage_status: evidence.coverage_status,
+    limitations: evidence.limitations,
+  };
 
   // 6. Impact / Effort / Confidence (ICE) Prioritization Matrix
   const iceMatrix = buildIceMatrix(findings, { type: 'findings' });
+  const qualifiedIceMatrix = {
+    ...iceMatrix,
+    determination_status: evidence.determination_status,
+    coverage_status: evidence.coverage_status,
+    limitations: evidence.limitations,
+    summary: {
+      ...iceMatrix.summary,
+      quick_wins_count: qualify(iceMatrix.summary.quick_wins_count),
+    },
+  };
 
   // 7. 30 / 90 / 180-Day CRO Strategic Roadmap tied to Measurable Conversion Outcomes
   const targetDomain = ctx.site.baseUrl ? new URL(ctx.site.baseUrl).hostname : 'target-site';
@@ -75,26 +103,36 @@ export async function auditCroSuite(root, { target, baseUrl, refDate, input, fun
     findings,
     targetDomain,
   });
+  const qualifiedRoadmap = {
+    ...croRoadmap,
+    determination_status: evidence.determination_status,
+    coverage_status: evidence.coverage_status,
+    limitations: evidence.limitations,
+  };
 
   const result = {
     fact_status: 'modeled_cro_evaluation',
     target: ctx.site.baseUrl || target,
     total_pages_audited: pages.length,
+    coverage_status: evidence.coverage_status,
+    determination_status: evidence.determination_status,
+    evidence_scope: evidence.evidence_scope,
+    limitations: evidence.limitations,
     summary: {
       conversion_readiness_score: avgConversionReadiness,
       atf_clarity_score: avgAtfClarity,
       trust_credibility_score: avgTrustScore,
-      funnel_health_score: funnelAnalysis.funnel_health_score,
+      funnel_health_score: qualifiedFunnel.funnel_health_score,
       total_cro_findings: findings.length,
-      planned_experiments: experimentBacklog.total_experiments,
-      quick_wins_count: iceMatrix.summary.quick_wins_count,
+      planned_experiments: qualifiedExperimentBacklog.total_experiments,
+      quick_wins_count: qualifiedIceMatrix.summary.quick_wins_count,
     },
-    funnel_analysis: funnelAnalysis,
+    funnel_analysis: qualifiedFunnel,
     pages: auditedPages,
     behavioral_telemetry: behavioralAnalysis,
-    experiment_backlog: experimentBacklog,
-    ice_matrix: iceMatrix,
-    strategic_roadmap: croRoadmap,
+    experiment_backlog: qualifiedExperimentBacklog,
+    ice_matrix: qualifiedIceMatrix,
+    strategic_roadmap: qualifiedRoadmap,
     findings: findings.map((f) => ({
       detector_id: f.detector_id,
       severity: f.classification.severity,

package/src/commands/delivery.js

@@ -6,6 +6,7 @@ import { compareSnapshots } from './compareSnapshots.js';
 import { buildAlertPayload, dispatchAlertWebhook, filterAlerts } from '../monitoring/alertDelivery.js';
 import { loadRegistries } from '../registries/index.js';
 import { readJson, sha256, writeJson, nowIso } from '../shared/io.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 
 const PKG = readJson(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../package.json'));
 
@@ -114,12 +115,11 @@ function annotationLevel(severity) {
 export function projectGithub(root, { runId } = {}) {
   if (!runId) throw new Error('projection requires a source run id');
   const runDir = path.join(root, '.citable', 'runs', runId);
-  const findingsFile = path.join(runDir, 'findings.json');
-  const manifestFile = path.join(runDir, 'manifest.json');
-  if (!fs.existsSync(findingsFile) || !fs.existsSync(manifestFile)) throw new Error(`run ${runId} is missing findings or manifest evidence`);
-  const findingsBytes = fs.readFileSync(findingsFile);
-  const manifestBytes = fs.readFileSync(manifestFile);
-  const annotations = JSON.parse(findingsBytes).map((finding) => ({
+  const loaded = loadVerifiedRun(runDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+  const findingsHash = loaded.artifactHashes?.['findings.json'];
+  const manifestHash = loaded.artifactHashes?.['manifest.json'];
+  if (!findingsHash || !manifestHash) throw new Error(`run ${runId} has no loader-verified findings or manifest hash`);
+  const annotations = loaded.findings.map((finding) => ({
     level: annotationLevel(finding.classification.severity),
     title: `${finding.detector_id}: ${finding.classification.severity}`,
     message: finding.observation.summary,
@@ -127,7 +127,7 @@ export function projectGithub(root, { runId } = {}) {
     line: finding.subject.source_location ? Number(String(finding.subject.source_location).match(/\d+/)?.[0]) || null : null,
     finding_id: finding.finding_id,
   }));
-  const projection = { source_run_id: runId, source_manifest_hash: sha256(manifestBytes), source_findings_hash: sha256(findingsBytes), generated_at: nowIso(), projection: 'github-check-annotations', authoritative: false, annotations };
+  const projection = { source_run_id: runId, source_manifest_hash: manifestHash, source_findings_hash: findingsHash, generated_at: nowIso(), projection: 'github-check-annotations', authoritative: false, annotations };
   const dir = path.join(root, '.citable', 'projections', 'github', runId);
   writeJson(path.join(dir, 'annotations.json'), projection);
   return { ...projection, dir };

package/src/commands/governance.js

@@ -1,8 +1,8 @@
-import fs from 'node:fs';
 import path from 'node:path';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 import { createRun } from '../evidence/run.js';
 import { loadRegistries, checkReferentialIntegrity } from '../registries/index.js';
-import { readJson, sha256, parseRefDate } from '../shared/io.js';
+import { sha256, parseRefDate } from '../shared/io.js';
 
 function recordHash(value) {
   return sha256(JSON.stringify(value));
@@ -79,8 +79,8 @@ export function validateGovernance(root, { refDate } = {}) {
   const evidence = new Map(registries.evidence.entries.map((item) => [item.evidence_id, item]));
   const activeByFinding = new Map();
   for (const exception of registries.exceptions.entries) {
-    const file = path.join(root, '.citable', 'runs', exception.source_run_id, 'findings.json');
-    const findings = new Map(fs.existsSync(file) ? readJson(file).map((item) => [item.finding_id, item]) : []);
+    const runDir = path.join(root, '.citable', 'runs', exception.source_run_id);
+    const findings = new Map(loadVerifiedRun(runDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings.map((item) => [item.finding_id, item]));
     const exceptionIssues = exceptionProblems(exception, policies.get(exception.policy_id), reviewers, findings, evidence, reference);
     problems.push(...exceptionIssues.map((problem) => `exceptions/${exception.exception_id}: ${problem}`));
     if (exceptionIssues.length === 0) {
@@ -98,10 +98,9 @@ export function validateGovernance(root, { refDate } = {}) {
 
 export function evaluateDispositions(root, { runId, refDate } = {}) {
   if (!runId) throw new Error('source run id is required');
-  const findingsFile = path.join(root, '.citable', 'runs', runId, 'findings.json');
-  if (!fs.existsSync(findingsFile)) throw new Error(`source findings not found for run ${runId}`);
-  const sourceBytes = fs.readFileSync(findingsFile);
-  const sourceFindings = JSON.parse(sourceBytes);
+  const runDir = path.join(root, '.citable', 'runs', runId);
+  const sourceRun = loadVerifiedRun(runDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+  const sourceFindings = sourceRun.findings;
   const findings = new Map(sourceFindings.map((item) => [item.finding_id, item]));
   const { registries, problems } = loadRegistries(root);
   const integrity = checkReferentialIntegrity(registries);
@@ -130,8 +129,8 @@ export function evaluateDispositions(root, { runId, refDate } = {}) {
       problems: matches.flatMap((item) => item.problems),
     };
   });
-  const run = createRun(root, { command: 'governance evaluate', argv: [runId], target: { kind: 'registries', location: findingsFile } });
-  run.addInput('source-findings', sourceBytes);
+  const run = createRun(root, { command: 'governance evaluate', argv: [runId], target: { kind: 'registries', location: path.join(runDir, 'findings.json') } });
+  run.manifest.input_hashes['source-findings'] = sourceRun.artifactHashes['findings.json'];
   run.addInput('exceptions', registries.exceptions);
   run.addInput('review-policies', registries.review_policies);
   run.writeArtifact('dispositions.json', dispositions);

package/src/commands/implementationKit.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 import { readJson, nowIso } from '../shared/io.js';
 import { remediateCommand } from './remediate.js';
 
@@ -76,7 +77,7 @@ export async function exportImplementationKit(root, options = {}) {
   if (!runId || !fs.existsSync(path.join(runDir, 'findings.json'))) {
     throw new Error(`source run not found: .citable/runs/${runId || '(none)'}`);
   }
-  const findings = readJson(path.join(runDir, 'findings.json'));
+  const findings = loadVerifiedRun(runDir, { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings;
   const matches = findings.filter((f) =>
     (f.detector_id || '').toUpperCase() === String(finding || '').toUpperCase()
     && (!subject || (f.subject?.identifier || f.subject?.url) === subject));

package/src/commands/init.js

@@ -89,7 +89,14 @@ export function init(root, { force = false, seed = null } = {}) {
         package_manager: detected.package_manager,
         build_command: detected.build_commands[0] ?? null, test_command: detected.test_commands[0] ?? null,
       },
-      audit: { index_target_default: true, max_crawl_depth: 4, thin_content_words: 120, fetch_external: false },
+      audit: {
+        index_target_default: true,
+        max_pages: 500,
+        time_budget_seconds: 1800,
+        max_crawl_depth: 4,
+        thin_content_words: 120,
+        fetch_external: false,
+      },
     };
     const { valid, errors } = validateAgainst('config.schema.json', config);
     if (!valid) throw new Error(`generated config invalid: ${errors.join('; ')}`);

package/src/commands/previewCro.js

@@ -167,7 +167,7 @@ export function generateCroPreviewHtml({
     </div>
 
     <div class="findings-list">
-      <h3>Resolved CRO Defects (${findingItems.length})</h3>
+      <h3>Observed CRO Findings (${findingItems.length})</h3>
       ${findingItems.map((f) => `
         <div class="finding-row">
           <span><strong>${f.detector_id}</strong>: ${f.summary}</span>

package/src/commands/prioritize.js

@@ -13,6 +13,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
 import { buildIceMatrix, formatIceMatrixOutput } from '../analysis/iceMatrix.js';
@@ -96,7 +97,7 @@ function initiativeMatrix(file, root, rest = []) {
   if (runId) {
     const findingsPath = path.join(root, '.citable', 'runs', runId, 'findings.json');
     if (!fs.existsSync(findingsPath)) throw new Error(`run ${runId} findings.json not found`);
-    const findings = JSON.parse(fs.readFileSync(findingsPath, 'utf8'));
+    const findings = loadVerifiedRun(path.dirname(findingsPath), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings;
     const matrix = buildIceMatrix(findings, { type: 'findings' });
     return { ...matrix, formatted: formatIceMatrixOutput(matrix) };
   }
@@ -106,7 +107,7 @@ function initiativeMatrix(file, root, rest = []) {
   if (fs.existsSync(runsDir)) {
     const runs = fs.readdirSync(runsDir).filter((r) => fs.existsSync(path.join(runsDir, r, 'findings.json'))).sort().reverse();
     if (runs.length > 0 && rest.includes('--findings')) {
-      const findings = JSON.parse(fs.readFileSync(path.join(runsDir, runs[0], 'findings.json'), 'utf8'));
+      const findings = loadVerifiedRun(path.join(runsDir, runs[0]), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings;
       const matrix = buildIceMatrix(findings, { type: 'findings' });
       return { ...matrix, formatted: formatIceMatrixOutput(matrix) };
     }

package/src/commands/reviews.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 import { loadRegistries, saveRegistry } from '../registries/index.js';
 import { readJson, readYaml, sha256, nowIso } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
@@ -23,7 +24,7 @@ export function queueReviews(root, { runId, policyId, write = false }) {
   if (!runId || !policyId) throw new Error('reviews queue requires <run-id> <policy-id>');
   const file = path.join(root,'.citable','runs',runId,'findings.json');
   if (!fs.existsSync(file)) throw new Error(`source findings not found for run ${runId}`);
-  const findings = readJson(file);
+  const findings = loadVerifiedRun(path.dirname(file), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings;
   const { registries, problems } = loadRegistries(root);
   if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
   if (!registries.review_policies.entries.some((p) => p.policy_id === policyId && p.status === 'active')) throw new Error(`active review policy not found: ${policyId}`);
@@ -40,7 +41,7 @@ export function queueReviews(root, { runId, policyId, write = false }) {
 export function prioritizeReviews(root, { write = false } = {}) {
   const { registries, problems } = loadRegistries(root); if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
   const cache = new Map();
-  const entries = registries.review_items.entries.map((item) => { const file=path.join(root,'.citable','runs',item.source_run_id,'findings.json'); if(!cache.has(file)) cache.set(file,fs.existsSync(file)?new Map(readJson(file).map(f=>[f.finding_id,f])):new Map()); const ranked=priority(item,cache.get(file).get(item.finding_id)); return {...item,priority_score:ranked.score,priority_tier:ranked.tier,missing_inputs:ranked.missing}; });
+  const entries = registries.review_items.entries.map((item) => { const file=path.join(root,'.citable','runs',item.source_run_id,'findings.json'); if(!cache.has(file)) cache.set(file,fs.existsSync(file)?new Map(loadVerifiedRun(path.dirname(file), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings.map(f=>[f.finding_id,f])):new Map()); const ranked=priority(item,cache.get(file).get(item.finding_id)); return {...item,priority_score:ranked.score,priority_tier:ranked.tier,missing_inputs:ranked.missing}; });
   if(write) saveRegistry(root,'review_items',{...registries.review_items,entries});
   return { items:entries.sort((a,b)=>b.priority_score-a.priority_score), written:write };
 }
@@ -67,7 +68,32 @@ export function selectSample(root,{planId,write=false}) {
 }
 
 export function evaluateReviews(root) {
-  const {registries,problems}=loadRegistries(root); const reviewers=new Map(registries.reviewers.entries.map(r=>[r.reviewer_id,r])); const results=[];
-  for(const item of registries.review_items.entries){const issues=[];const binding=reviewBindingHash(item);const source=path.join(root,'.citable','runs',item.source_run_id,'findings.json');const finding=fs.existsSync(source)?readJson(source).find(f=>f.finding_id===item.finding_id):null;if(!finding||sha256(JSON.stringify(finding))!==item.finding_hash)issues.push('source finding is unavailable or changed');for(const d of item.decisions){const r=reviewers.get(d.reviewer_id);const reviewRole=r?.roles.some(role=>['technical_reviewer','subject_matter_reviewer','independent_reviewer'].includes(role));if(!r||r.status!=='active'||!reviewRole||!item.assigned_reviewer_ids.includes(d.reviewer_id))issues.push(`${d.reviewer_id} is not an active assigned semantic reviewer`);if(d.review_item_hash!==binding)issues.push(`${d.reviewer_id} decision is stale`);}const verdicts=[...new Set(item.decisions.map(d=>d.verdict))];let state=item.decisions.length?'completed':'review_required';if(verdicts.length>1){state='adjudication_required';const a=reviewers.get(item.adjudication?.reviewer_id);if(item.adjudication&&a?.status==='active'&&a.roles.includes('independent_reviewer')&&item.adjudication.review_item_hash===binding)state='completed';else issues.push('reviewer disagreement requires a current decision from an active independent adjudicator');}results.push({review_item_id:item.review_item_id,state,verdict:state==='completed'&&!issues.length?(item.adjudication?.verdict||verdicts[0]):null,issues});}
-  return {ok:problems.length===0&&results.every(r=>!r.issues.length),problems,results};
+  const { registries, problems } = loadRegistries(root);
+  const reviewers = new Map(registries.reviewers.entries.map((r) => [r.reviewer_id, r]));
+  const results = [];
+  for (const item of registries.review_items.entries) {
+    const issues = [];
+    const binding = reviewBindingHash(item);
+    const source = path.join(root, '.citable', 'runs', item.source_run_id, 'findings.json');
+    const finding = fs.existsSync(source)
+      ? loadVerifiedRun(path.dirname(source), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false }).findings.find((f) => f.finding_id === item.finding_id)
+      : null;
+    if (!finding || sha256(JSON.stringify(finding)) !== item.finding_hash) issues.push('source finding is unavailable or changed');
+    for (const decision of item.decisions) {
+      const reviewer = reviewers.get(decision.reviewer_id);
+      const reviewRole = reviewer?.roles.some((role) => ['technical_reviewer', 'subject_matter_reviewer', 'independent_reviewer'].includes(role));
+      if (!reviewer || reviewer.status !== 'active' || !reviewRole || !item.assigned_reviewer_ids.includes(decision.reviewer_id)) issues.push(`${decision.reviewer_id} is not an active assigned semantic reviewer`);
+      if (decision.review_item_hash !== binding) issues.push(`${decision.reviewer_id} decision is stale`);
+    }
+    const verdicts = [...new Set(item.decisions.map((d) => d.verdict))];
+    let state = item.decisions.length ? 'completed' : 'review_required';
+    if (verdicts.length > 1) {
+      state = 'adjudication_required';
+      const adjudicator = reviewers.get(item.adjudication?.reviewer_id);
+      if (item.adjudication && adjudicator?.status === 'active' && adjudicator.roles.includes('independent_reviewer') && item.adjudication.review_item_hash === binding) state = 'completed';
+      else issues.push('reviewer disagreement requires a current decision from an active independent adjudicator');
+    }
+    results.push({ review_item_id: item.review_item_id, state, verdict: state === 'completed' && !issues.length ? (item.adjudication?.verdict || verdicts[0]) : null, issues });
+  }
+  return { ok: problems.length === 0 && results.every((r) => !r.issues.length), problems, results };
 }

package/src/commands/roadmapCmd.js

@@ -1,8 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { contextDir, loadRegistryFile } from '../registries/index.js';
-import { readJson, writeJson } from '../shared/io.js';
+import { writeJson } from '../shared/io.js';
 import { buildStrategicRoadmap, formatRoadmapMarkdown } from '../analysis/strategicRoadmap.js';
+import { loadVerifiedRun } from '../shared/verifiedRunLoader.js';
 
 /**
  * `citable roadmap [generate|show]` — generate or view the 30/90/180-day strategic roadmap.
@@ -10,6 +11,7 @@ import { buildStrategicRoadmap, formatRoadmapMarkdown } from '../analysis/strate
 export async function roadmapCommand(root, { runId, target, write = true } = {}) {
   let findings = [];
   let initiatives = [];
+  let verifiedRun = null;
 
   // 1. Load findings from specified or latest run
   const runsDir = path.join(root, '.citable', 'runs');
@@ -20,10 +22,8 @@ export async function roadmapCommand(root, { runId, target, write = true } = {})
   }
 
   if (sourceRun) {
-    const findingsFile = path.join(runsDir, sourceRun, 'findings.json');
-    if (fs.existsSync(findingsFile)) {
-      findings = JSON.parse(fs.readFileSync(findingsFile, 'utf8'));
-    }
+    verifiedRun = loadVerifiedRun(path.join(runsDir, sourceRun), { requireCompletedExecution: false, allowLegacy: true, requireCoverage: false });
+    findings = verifiedRun.findings;
   }
 
   // 2. Load initiatives if present
@@ -39,14 +39,8 @@ export async function roadmapCommand(root, { runId, target, write = true } = {})
 
   // Target domain resolution
   let domain = target || 'nebulacomponents.com';
-  if (sourceRun) {
-    const manifestFile = path.join(runsDir, sourceRun, 'manifest.json');
-    if (fs.existsSync(manifestFile)) {
-      try {
-        const manifest = readJson(manifestFile);
-        if (manifest.target?.location) domain = manifest.target.location;
-      } catch {}
-    }
+  if (verifiedRun?.manifest?.target?.location) {
+    domain = verifiedRun.manifest.target.location;
   }
 
   const roadmap = buildStrategicRoadmap({ findings, initiatives, targetDomain: domain });

package/src/commands/sweep.js

@@ -4,6 +4,7 @@ import { parse as parseHtml } from 'node-html-parser';
 import { buildContext } from './context.js';
 import { selectDetectors } from '../detectors/index.js';
 import { runDetectors, indexTargets, pageSubject, safePath } from '../detectors/framework.js';
+import { downstreamEnvelope, scoreFromCoverage, completeLocalCoverage } from '../evidence/downstream.js';
 
 /**
  * CWV standard thresholds per Google / web.dev guidance
@@ -223,6 +224,9 @@ export async function sweepTechnical(root, { target, baseUrl, refDate, page: pag
     if (!pages.length) throw new Error(`page not found in audited output: ${pageFilter}`);
   }
 
+  const coverage = ctx.coverage || (pages.length > 0 ? completeLocalCoverage(pages, ctx.site.baseUrl) : null);
+  const evidence = downstreamEnvelope(coverage);
+
   // 3. Aggregate Core Web Vitals across audited pages
   const pageVitals = [];
   let totalLcpBlockers = 0;
@@ -269,6 +273,8 @@ export async function sweepTechnical(root, { target, baseUrl, refDate, page: pag
   } else if (highFindings.length > 0 || totalLcpBlockers > 3 || totalClsRisks > 5) {
     overallHealth = 'needs_attention';
   }
+  if (evidence.determination_status === 'indeterminate') overallHealth = 'not_established';
+  else if (evidence.determination_status === 'qualified' && overallHealth === 'optimal') overallHealth = 'qualified';
 
   const result = {
     target: ctx.site.baseUrl || target,
@@ -291,7 +297,9 @@ export async function sweepTechnical(root, { target, baseUrl, refDate, page: pag
         total_inp_risks: totalInpRisks,
         unsized_images: totalUnsizedImages,
         total_images: totalImagesCount,
-        image_dimension_coverage_pct: totalImagesCount > 0 ? Math.round(((totalImagesCount - totalUnsizedImages) / totalImagesCount) * 100) : 100,
+        image_dimension_coverage_pct: evidence.determination_status === 'supported' && totalImagesCount > 0
+          ? scoreFromCoverage(totalImagesCount - totalUnsizedImages, { ...coverage, populations: { ...coverage.populations, evaluated: totalImagesCount } })
+          : null,
       },
       pages: pageVitals,
     },
@@ -310,6 +318,10 @@ export async function sweepTechnical(root, { target, baseUrl, refDate, page: pag
       summary: f.observation.summary,
       remediation: f.remediation?.preferred,
     })),
+    coverage_status: evidence.coverage_status,
+    determination_status: evidence.determination_status,
+    evidence_scope: evidence.evidence_scope,
+    limitations: evidence.limitations,
   };
 
   return result;
@@ -325,6 +337,7 @@ export function formatSweepOutput(r) {
     `Target: ${r.target}`,
     `Pages Audited: ${r.total_pages_audited}`,
     `Overall Health: ${r.overall_health.toUpperCase()}`,
+    `Evidence Determination: ${(r.determination_status || 'not_established').toUpperCase()} (coverage: ${r.coverage_status || 'unknown'})`,
     ``,
     `CRAWL & INDEXABILITY:`,
     `  HTTP 200 OK: ${r.crawl_and_indexability.status_200_count}/${r.total_pages_audited}`,
@@ -335,7 +348,7 @@ export function formatSweepOutput(r) {
     `CORE WEB VITALS READINESS (Deterministic Static Audit):`,
     `  LCP Readiness: ${r.core_web_vitals.summary.lcp_readiness.toUpperCase()} (${r.core_web_vitals.summary.total_lcp_blockers} potential render blocker(s))`,
     `  INP Readiness: ${r.core_web_vitals.summary.inp_readiness.toUpperCase()} (${r.core_web_vitals.summary.total_inp_risks} DOM complexity risk(s))`,
-    `  CLS Readiness: ${r.core_web_vitals.summary.cls_readiness.toUpperCase()} (${r.core_web_vitals.summary.unsized_images}/${r.core_web_vitals.summary.total_images} images lack dimensions; ${r.core_web_vitals.summary.image_dimension_coverage_pct}% coverage)`,
+    `  CLS Readiness: ${r.core_web_vitals.summary.cls_readiness.toUpperCase()} (${r.core_web_vitals.summary.unsized_images}/${r.core_web_vitals.summary.total_images} images lack dimensions; ${r.core_web_vitals.summary.image_dimension_coverage_pct == null ? 'not evidenced' : `${r.core_web_vitals.summary.image_dimension_coverage_pct}%`} coverage)`,
     ``,
     `CWV Threshold Standards:`,
     `  - LCP: <= ${CWV_THRESHOLDS.lcp.good}s (Good), <= ${CWV_THRESHOLDS.lcp.needs_improvement}s (Needs Improvement)`,